Markdown Syntax Reference

To get started, we will cover the core Markdown syntax including features added by Notebooks. Then we will go over the extensions offered by Notebooks‘ included converters Discount (Notebooks‘ default converter) and MultiMarkdown, which bring their own set of extensions as well.

Markdown Syntax incl. Notebooks Extensions

The standard Markdown syntax as defined by John Gruber is documented at his Markdown website. This chapter is a summary and includes the extensions added by Notebooks.

Paragraphs and Newlines

By Markdown standards, a single newline won’t create a line break. Instead, you need to end a line with two consecutive spaces to see a line break in the rendered output.

Make Every Newline a Line Break

While requiring two spaces at the end of a line improves readability in plain text, it can be a hassle for users. That is why Notebooks provides a setting called Make every newline a line break. When you turn it on, Notebooks automatically adds two spaces at the end of each line, making sure that a return in your text always creates a line break in the rendered output.

Headers

To define a header, just start a line with 1-6 hash (#) characters, without any leading spaces. You can optionally terminate the header with the same number of hash characters. These are called atx style headers.

# This is a level one header (H1)  
## This is a level two header (H2) ##
###### This is a level six header (H6)

If you set Notebooks to highlight Markdown syntax, headings appear colorized with hanging indents, so the text is left aligned and easier to read.

Notebooks uses these headers to build the Table of Contents, and you can use them as cross references.

On your iPhone or iPad

On the row of extra keyboard keys you find a dedicated key ## . Tap the button to increase the heading level of the current line or selection. Tap and hold it to reset the heading level to zero.

On your Mac

On a Mac, use the keyboard shortcuts cmd-1 to cmd-5 to assign the corresponding heading level to the current line or selection. Use cmd-0 to reset.

Headers – Setext Style

Alternatively, you can use Setext style headers, underlined with = or -. It is not required that the number underlines matches the number of characters in the title.

This is a level one header as well
==================================

And this is level two
---------------------

Anchors and Cross References

Markdown uses your headers for its Table of Contents and automatically creates anchors for this purpose. However, the anchors’ format depends on the Markdown converter you choose. So for the chapter Anchors and Cross References, for example, the anchors would look like this:

Default Converter:  Anchors-and-Cross-References
MultiMarkdown:      anchorsandcrossreferences

To avoid relying on the selected converter or create shorter anchors, you can optionally define them yourself. To do so, just add your anchor, enclosed in square brackets:

## Anchors and Cross References [anchors]  

So you can reference [the chapter](#anchors) like this.

Emphasis (Bold and 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***
this is _italic_, too, if you prefer

On your iPhone or iPad

The row of extra keyboard keys holds dedicated Markdown formatting keys BIUS which you can use to quickly set or clear the corresonding formatting characters. In addition to bold and italic, you can underline and strike through the text as well.
To remove the formatting characters from selected text, just use the same key.

On your Mac

Use the keyboard shortcuts cmd-B for Bold, cmd-I for Italic, cmd-U for underline and cmd-— for strike through. (Depending on your selected Markdown converter, strike through will use a different syntax.)
To clear the corresponding format, select the text without leading and trailing formatting characters, and use the same command again.

Highlight Text

Text highlighting is not supported by standard Markdown, but it is a convenient and frequently used way of emphasizing text, so Notebooks adopts a commonly used syntax.

To ==highlight text==, just place it between double equal signs.

When using an external keyboard, you can use shift-alt-cmd-H to add the equal signs to the selected text; if the selected text is already enclosed by equal signs, the keyboard shortcut removes them.

Lists: Bulleted, Ordered and Checklists

Notebooks supports three types of lists in Markdown: unordered, ordered and checklist.

On your iPhone or iPad

Notebooks provides a dedicated extra keyboard key to cycle through the list styles.

On your Mac

On a Mac or when using an external keyboard, you can use cmd-L to cycle through the list style for the current line or selection. Use shift-cmd-L to cycle through the sequence in reverse order.

Bulleted Lists

Bulleted or unordered lists use asterisk *, plus + or hyphen - as list markers.

- Red
- Green
- Blue

Ordered Lists

Ordered lists use a number followed by a period. The actual number you use has no effect on the result, lists always start at 1..

1. Red
2. Green
3. Blue

To avoid starting an ordered list by accident, escape the period like in this example:

10\. Anniversary

Checklists

Checklists are an extension of standard Markdown. In the rendered output, Notebooks displays them a clickable checkboxes, and when you click a checkbox, Notebooks updates the Markdown text to set the task’s state.

- [ ] Red
- [ ] Green
- [x] Blue ... this renders as a "done" item in the list

This is what the rendered version of the checklist looks like if you use any of Notebooks‘ document styles, or if your custom style inherits from one of Notebooks‘:

Red
Green
Blue … this renders as a “done” item in the list

Autodetect and Align Lists
When working with lists, you could take advantage of Notebooks‘ setting to detect and align lists for you, which makes creating and managing lists a breeze. (Notebooks’ Settings > Write and Edit > Markdown).

When editing a list and typing return, Notebooks automatically creates a new list entry on the next new line.

To indent or outdent list items, you can use TAB andshift-TAB, or use the standard keyboard shortcuts cmd-] and cmd-[ on an external keyboard. On an iPhone or iPad, tap or tap and hold the ⇥ extra keyboard key.

Typing return on a line which contains nothing but a list marker outdents the line if possible, or terminates the list.

To improve readability, multiline paragraphs display with hanging indents, so the text aligns with the left edge of the first character, while list markers remains outdented.

Definition Lists (Description Lists)

Definition lists, which are also known as a description lists, can be used to group a set of terms and their corresponding definitions. You can see an example in the section about Footnotes below. Again, Notebooks supports multiple flavors:

PHP Markdown style definition lists look 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

If you use Notebooks‘ default converter, you can also use the following notation:

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

Blockquotes

Blockquotes by default are indented paragraphs, similar to quotes in email replies.

> This is quoted text.  
    > With a nested quote.

John Gruber describes more variations for blockquotes.

You can use blockquotes in different ways, and depending on their style and layout, they can serve as boxes, callouts etc. The section Autodetect and Align Lists above is actually a Markdown blockquote, which Notebooks displays in a way that calls your attention.

Code Blocks

The Markdown samples you see throughout this reference are formatted using Code Blocks. The text in code blocks is displayed verbatim, usually in a fixed width font and without extra formatting or line breaks.

The Markdown default is to indent a line with one tab or four spaces. You can further indent the code with more spaces and tabs.

While this is a regular paragraph,

    this is a code block

Fenced Code Blocks

With longer blocks, indenting the text may become difficult. So instead of regular code blocks, you can use Fenced Code Blocks by enclosing the lines with three backtick characters

  
```
This text appears as a code block, in back tick notation.
```

Fenced Code Blocks are especially convenient for code samples, as they allow you to specify the programming language. When using Notebooks‘ Source Code document style (or one inheriting from it), the code will be correctly highlighted.

  
``` html
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
...
</html>
```

Inline Code

In cases where you want to format just a few words or characters as code without giving them an extra section (display them inline), you can enclose them in backticks `.

Use the shortcut `cmd-S` to save a version in Notebooks for Mac.  
To use a single backtick in code, add `` ` ``.

Horizontal Line

To insert a horizontal line as thematic break, add three or more asterisks *, hyphens - or underscores _ on a line:

***

Links and Wiki Links

Standard Markdown supports inline links and reference-style links, and Notebooks adds support for Wiki-style links as well.

Inline Links

Inline links define text and URL in one space, with the link’s text in square brackets, immediately followed by the URL in parentheses. The URL can be any absolute or relative URL, including a reference to an anchor in the same document.

An inline link to [Notebooks](https://notebooksapp.com) looks like this.  
A link to a [section](#section) looks like that.

Reference-style Links

If you need to reuse the same URL multiple times in a document, reference style links may be more convenient. They use a label instead of the URL, which may result in more readable Markdown text. The label needs to be defined anywhere in the text.

This is a reference style link to [Notebooks][nbks].  

[nbks]: https://notebooksapp.com "Notebooks"

Another shortcut is to use the link text as label, in which case you can add empty square brackets instead of the label.

This is a reference style link to [Notebooks][].  

[Notebooks]: https://notebooksapp.com "Notebooks"

Again, John Gruber provides more examples.

Wiki Links

Wiki Links use a simpler, more consistent notation than standard Markdown. Their syntax usually consists of one phrase in double square brackets. The phrase is the link’s label and also its target.

Learn more about [[Link Management in Notebooks]].

Wiki links are flexible with a variety of options, and they are covered in more detail in a separate chapter.

Images

The notation for images is very similar to that of links, except for the leading !:

![an optional title for the image](screenshot.png)  
![another image][img]  

[img]: media/screenshot.jpeg

Comments

One of Notebooks‘ Markdown setting allows you to use comments in your Markdown text. Comments are lines or paragraphs of text which will not appear in the rendered output, so they are great for notes, revisions etc. To define a comment, just start a line with //.

// This is a comment which will not appear in the rendered output.

Notebooks handles comments similar to list, so when you type return on a line starting with //, Notebooks prefixes the next line with // as well. If you then type return again, Notebooks terminates your comment section.

Footnotes

Notebooks supports multiple flavors of footnotes. None of them in standard Markdown, but all notations are supported by both of Notebooks‘ Markdown converters.

PHP Markdown Extra Notation: This is some text with a footnote [^1], but the footnote itself can be defined anywhere in the text; it needs to start at the beginning of a line, though:
[^1]: Here is the footnote.
MultiMarkdown Inline Notation: MultiMarkdown allows you to define footnotes in place, which may make them easier to manage.[^Here is the text which becomes your footnote.].
Obsidian Style Inline Notation: This is a variation of the MultiMarkdown inline footnote (watch the position of the caret character): ^[Here is the footnote.]
Refnotes Notation: Finally, for compatibility with footnote and reference management tools, Notebooks supports the Refnotes notation as well: <<fnote "This is a Refnote style footnote">>

Class Blocks

Class blocks allow you to assign a specific class to the subsequent block of text:

> %class-name%
This text will be enclosed in <div class="class-name">.

These class blocks are an extension added by Discount, but the are so convenient that Notebooks supports them in both converters.

Pagebreak

When preparing a document for print or PDF output, proper page breaks are essential. There is no standard syntax in Markdown, so Notebooks uses its own notation:

{{pagebreak}}

Internally, Notebooks uses Discount‘s class block syntax to implement page breaks, so you could also use:

> %pagebreak%

On screen, this page break produces a horizontal line labeled “Page Break”, in print it produces a page break.

Please note: the Document Style you use must inherit from any of Notebooks‘ predefined styles to guarantee that page breaks work as expected.

The table of contents is a structured list of clickable links to the headers in the document. One way to add the table to your Markdown document is to select Show TOC from a document’s action menu. By default, this adds the table of contents at the top of the document – or just below the Pandoc header, in case you use one.

However, Notebooks gives you more options to control position and content of your Table of Contents with the following notations. Please note that you need to add an empty line above and below:

Notation	Output
`<TOC>`	Insert the full TOC at this position
`{{TOC}}`	Same as above, but more standard
`{{TOC:2}}`	TOC for level 2 headers only
`{{TOC:2-}}`	TOC for level 2 and higher
`{{TOC:2-3}}`	TOC for level 2 and level 3 only

Tables

Tables in Notebooks follow the definition of Michael Fortin’s PHP Markdown. Here is an example of a table with two columns:

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

Standard HTML Code

For any formatting that is not available in Markdown, you can use HTML. There’s no need for special prefixes or delimiters—just use the HTML tags directly.

Markdown Syntax Extensions Provided by Discount

Notebooks‘ default Markdown converter Discount adds a few extras which are not available in standard Markdown, and not in MultiMarkdown, Notebooks’ alternative converter, either.

Struck Through Text

To render text as ~~struck through~~, enclose enclose it with ~~.

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

When using an external keyboard, you can use the keyboard shortcut cmd-—. If you use MultiMarkdown as converter, this shortcut will insert the HTML code instead.

Centered Alignment

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

->This is a centered paragraph.<-

Fenced Blocks – Alternative

As alternative to the backtick notation, enclose the lines of text with at least three ~ characters.

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

Pandoc Style Document Headers

If the first three lines in your document begin with a % character, Notebooks recognizes them as document header:

% Title
% Author
% Date

When creating the rendered version, Notebooks uses the document header to produce a formatted title.

Notebooks‘ built in document styles define a specific layout for this header, using H1.title, H2.author and H3.date.

Markdown Syntax Extensions Provided by MultiMarkdown

MultiMarkdown is a very capable Markdown converter with many additional options like Glossaries, Abbreviations, File Transclusion, and much more. The detailed and most up to date documentation is available on the MultiMarkdown website, but we provide a summary of the most important options here for quick reference.

Please note that these extensions are not supported by Notebooks default Markdown converter.

Abbreviations

[>NBKS] is an abbreviation, defined further down. [>(MD) Markdown] is another abbreviation, defined inline.

[>NBKS]: Notebooks

Citations

You can use reference style citations to attribute a source [p. 23][#NB:2018], but you can also use them inline [#Notebooks. *The Joy of Writing*. 2016.]

[#NB:2018]: Notebooks. *Don't Fear the Blank Page*. 2018.

Citations are appended at the end of the document, in their own section, similar to footnotes.

CriticMarkup

With CriticMarkup editors and authors can track changes in plain text documents. It uses five types of marks to denote changes:

Addition {++ ++}
Deletion {-- --}
Substitution {~~ ~> ~~}
Comment {>> <<}
Highlight {== ==}{>> <<}

By default, Notebooks incorporates (accepts) the tracked changes in the rendered output, so the marks are invisible. You can toggle their visibility from the document’s ••• menu.

Glossaries

By default, the glossary is appended at the end of the document, similar to footnotes and citations. When used with LaTeX (by duplicating a Markdown document as LaTeX), you can build a Glossary chapter at the end of the document.

As usual, you can define an inline [?(glossary) The glossary collects information about important terms used in your document], or you can use the [?Reference Style].

[?reference style]: Reference style adds the definition of the glossary term elsewhere in the document.