Project

General

Profile

Q&A » PubWriter FAQ »

Markdown Formatting

Added by Brian Schwartz over 8 years ago

You can do a lot of fancy formatting in PubWriter, but it does require that you use Markdown to do it.

Here are a few of the more popular Markdown formatting programs/apps:

What is markdown?

Markdown is how you format your text for your PubWriter site. You can add italics, bold, images, headers, dividers, and more.

Markdown is what is known as a 'semantic editor.'

Some helpful (& recommended) tutorials to start with:

Both PubWriter and AuthorDock use a simple form of Semantic Publishing. The semantics you use define how the text is rendered in HTML. The beauty of writing semantically is that your text is 'jail broken' and compatible with nearly any program. The problem of writing in Word, Pages, Open Office, or any other word processor is that your document will contain proprietary formatting unique to the application you built it with. This means unless the user has the same program as you do, you can't necessarily open it edit it. When you start copying & pasting between programs, formatting gremlins tend to creep in with those proprietary programs. Markdown is open source formatting.

Whenever you see .md on a filename, it was saved in markdown.

There are dozens of markdown editors and more are released every year. They are lightweight applications that run on any OS. The best part is that the .md file you create will be compatible with all of them!

Some work better with PubWriter than others. A few of my favorites (PubWriter preferred) include:

Here are a few of the more popular Markdown formatting programs/apps:

Tons of markdown (aka plain text) editors exists for 3 main platforms: Web-based editors, PC, and Mac.

Here are some of the main ones as of early 2017:

Mac / iOS

You can also search the Apple app store - when I last check, there were dozens. One of the more advanced writers is called Ulysses and it has a huge fan base (it's got a bit more of a learning curve). Scrivner also has an export to markdown option, but I haven't used it yet and my understanding is that Scrivner becomes problematic when you try to setup your print edition (the export to word is not so great).

PC

Web-based

Any plain text editor will also work. Two of the most popular are Notepad++ on the PC and TextWranger on the Mac. You can preview the results on your own Markdown site or use one of the Markdown previewers like Marked or Markoff (both for the mac). I'm looking for one for the PC.

AuthorDock gives you the ability save files in .md format from both the pages and war rooms modules.

I favor Atom.io because of the ability to seamlessly move between the mac & pc and work with a hacker theme.

Also, there's an extensive list of Markdown editors (including web-based, mac and PC) on Mashable

You are sure to find one that exactly to your liking!

Here are some very slick tools to help you convert existing documents to Markdown:

Check out Cloud Convert for a bunch of conversion options (disclaimer - I haven't done much testing with it yet).

Here's a good tutorial:
http://markdowntutorial.com/

Section breaks (helpful lines to distinguish break sections):

it's 3 asterisks in a row:
***

Paragraph formatting

Heading 1

Heading 2

Heading 3

(you can go up to 6 headings if you really need to!)

Character formatting

ITALIC

or

ITALIC

BOLD

**BOLD+ITALIC*

or

BOLD+ITALIC

strikethrough

Bulleted Lists:

  • Item 1
  • Item 2
    • Item 2a
    • Item 2b

Numbered Lists

  1. Item 1
  2. Item 2
  3. Item 3
    • Item 3a
    • Item 3b

Hyperlinks to external websites (2 methods):

Option 1: You fence the full http url with <http://www.website.com>

Option 2: Or, you can link a work like this: [this link](http://url.com)

Quotes (aka comment boxes, callouts):

You can use > or >> or even >>>
depends on how deep you want to go. 99% of the time, just use ' > '

Plain text formatting:

Plain Text Formatting

Hidden text

One of the secret tricks you can do with markdown is to wrap any text with < > - for example will hide the word 'text' when it gets converted to markdown.

This is helpful for editor comments to the author you want hidden from the reader.

Paragraph formatting note:

If you want to do a 'soft break' - you need to add two spaces at the end of the line.

Images

In order to insert an image, it has to first exist online and be linkable. Sites like Imgur makes this pretty simple, but you can also use dropbox and flickr.

(IF you do use dropbox (recommended), then put all your images in the PUBLIC folder so you get the correct dl.dropboxusercontent.com link.

You type the following syntax:
![](image url)

Anchors within a page

Anchors require a little bit of HTML.

First: You have to create a unique anchor (identifier). For example:

<a name="1"></a>

In this case, 1 is the anchor.

Second: You have to point to the anchor, in a similar way you always link, but instead of a URL, you put #:
[text](#1)

[text](#1)

You can even link directly to an anchor on a page from another page like this:

http://read.pubwriter.com/path.md#agreements

What that link above takes you to is a specific location (anchored with #agreements) on that page.

Here are a couple screenshots to help you grasp how to do it:

First I created an anchor called 'top':

Second, I created a link to the anchor elsewhere on my page:

Endnotes/Footnotes

(coming soon)

END

Here's some more helpful tutorials on using Markdown:

https://michelf.ca/projects/php-markdown/concepts/

https://dayone.zendesk.com/hc/en-us/articles/200265094-Markdown-Guide

http://www.engadget.com/2010/12/29/markdown-primer/

http://brettterpstra.com/why-markdown-a-two-minute-explanation/

https://dayone.zendesk.com/hc/en-us/articles/200145825-What-is-Markdown-

Here's a downloadable Markdown handbook:

https://dl.dropboxusercontent.com/s/lk1kx8tfy3hjqtm/markdown-guide.pdf