Markdown

Markdown is a simple set of rules to style and format plain text. Markdown is also a tool to convert these rules to perfectly formatted HTML. It is an alternative for those who do not like WYSIWYG editing, and for those who just appreciate the flexibility and simplicity of Markdown.

What are Notebooks’ Markdown Documents?

Although Markdown is a set of rules and a process to convert plain text to HTML, we use the term Markdown document to refer to a type of document that is displayed as a formatted HTML document, but edited as plain (Markdown) text.

When you decide to treat a plain text note as a Markdown document, Notebooks provides two options:

  1. Notebooks changes the path extension from .txt to .md. The document remains a plain text document, but when you open it in Notebooks, it is first appears in its formatted form.
  2. Notebooks converts the note and saves it as an HTML document, but it also preserved the original plain text. When editing, Notebooks switches to the plain text version, which allows you to continue working on the Markdown text of your document. All changes you make to the Markdown text are converted to HTML when you hide the keyboard or tap the Done button. (We call this type of document a Combined Markdown Document.)

An switch in Notebooks’ settings controls which option is used.

Advantages of Using Markdown

  • The documents are always easily readable.
  • After conversion, documents are perfectly valid HTML that you can mail, print, share, sync etc.
  • The documents remain in a standard format (either plain text or HTML) and can be reused and edited on the computer, without the need of any dedicated software (Pages etc.)
  • If your blog supports Markdown, you can prepare an entry in Notebooks, make sure it is correctly formatted, and then copy the Markdown code to your blog.
    If your blog supports HTML only, just copy HTML code that Notebooks generates from the Markdown document and create a blog entry from that.
  • Additional tools are available to convert Markdown documents to RTF or even PDF on a computer. Notebooks and Markdown can be a good starting point for a publishing process. (see MultiMarkdown)

Basic Operation

Convert a Plain Text Note to a Formatted Document

Select Process > Format Document… from a plain text document’s action menu. Notebooks presents a preview of the converted document, and from there you can decide how to proceed:

  • Save a formatted copy of the document which can be edited in Notebooks.
  • Treat as Markdown converts the document to a Markdown document, using one of the options described above.
  • Copy the HTML code to the clipboard so you can paste it into your blog, for example.
  • Email the HTML document.

Notebooks’ formatted documents do not use the background pattern you may have selected for your plain text documents. The reason is that the line spacing is very uneven in formatted documents, and displaying them on a regularly checked or ruled background would look odd.

Switch between Formatted and Editable Representation

  • To edit a Markdown document, tap the text.
  • To return to the formatted view, hide the keyboard or move to a different note. This will also commit the changes you made.

Convert a Markdown Document to Plain Text

If you converted a note to a combined document by accident, use the action Copy as Plain Text to extract an unformatted copy. If you no longer need the formatted version you can delete it.

Modify a Markdown Document on your Computer

The easiest way to edit Notebooks’ formatted Markdown documents is in Notebooks for Mac/PC, but you can edit them in any text editor. This is straight forward for Markdown documents stored as plain text (.md), but it may require some explanation for combined Markdown documents.

Combined Markdown documents are stored as HTML and will by default open in a browser on your computer. To edit, open those documents in a text editor instead (please make sure that this editor ignores HTML formatting).

The Markdown text is stored as an HTML comment at the top of the document, delimited by

<-- Plain Text Representation  
your text  
-->

You can change and edit the plain text, but please consider the following restrictions:

  • You may remove the comment tags and the HTML code and just leave the plain Markdown text; the next time you open that document in Notebooks, the HTML version will be rebuilt.
  • If you do not delete tags and HTML code, please make sure not to change or delete the comment tags, either..
  • Changes you make to the HTML code of the document will be ignored and overwritten by Notebooks.

The next time you open this document in Notebooks, your edits to the plain text representation will be converted to HTML.

The Markdown Rules

Now the core of Markdown, its syntax. The list might look extensive (and thus a bit intimidating), but the most important options are available through Notebooks’ extra keys anyway. It might still be good to know what else Markdown and Notebooks have to offer. The full definition is available on John Gruber’s website, the most important tags are listed here:

Headers

Use one to six hash (#) characters at the start of the line, corresponding to header levels:

# This is a level one header  
## This is a level two header  
###### This is a level six header

Lists

Unordered lists use asterisk (*), plus (+), and hyphen (-) as list markers. Ordered lists use numbers followed by periods, but the actual numbers you use have no effect on the result.

- Red  
- Green  
- Blue

1. Red  
2. Green  
3. Blue

Horizontal Rule

Add three or more asterisks (*), hyphens (-) or underscores (_) on a line:

***

Bold, Italic

Use asterisks (*) and underscores (_) as indicators of emphasis. Text wrapped with one of these character appears italic, text wrapped with two characters appears bold.

this is *italic* and this is **bold**, and this is ***bold and italic***

Extended Markdown

Notebooks uses Discount, a great and fast open source Markdown converter by David Parson, which supports a few extras not available in standard Markdown. The most important additions are:

Struck through text

Wrap the text that should appear struck through with “~~”.

This is the code for ~~struck through~~text.

Centered Alignment

To center a paragraph, just wrap it with –> and <–

->This is a centered paragraph<-  

Tables

They follow the definition from Michael Fortin’s PHP Markdown

First Header  | Second Header  
------------- | -------------  
Content Cell  | Content Cell  
Content Cell  | Content Cell  

Footnotes

Text with a footnote.[^1]  
[^1]: Here is the footnote.

Definition lists

Wrap the tag with “=” and indent the definition with four spaces or one tab.

=Apple=
    Pomaceous fruit of plants of the genus Malus in the family Rosaceae.  
=Orange=
    The fruit of an ~~evergreen~~ tree of the genus Citrus  

Notebooks also supports PHP Markdown style definition lists like this:

  
Apple  
:   Pomaceous fruit of plants of the genus Malus in the family Rosaceae.  
Orange  
:   The fruit of an ~~evergreen~~ tree of the genus Citrus

Fenced Blocks

Surround the text with at least three ~ characters.

~~~  
This text appears as a code block  
~~~

Pandoc Style Document Headers

If the first three lines in the document begin with a % character, they are taken to be a document header in the form of

% Title  
% Author  
% Date  

During conversion to HTML, Notebooks uses this information to produce a formatted document header. You are not limited to this sequence, and instead of plain text you could add HTLM code, for example, and insert an image instead of an author’s name.