Markdown Documents

What is Markdown?

Markdown allows you to create formatted documents from plain text. By following a few simple rules you can add headings, lists, images, even tables to your text. The result is a perfectly readable plain text document which you can easily convert into a formatted document, to PDF or other presentations. The transformation is handled by a so-called Markdown Converter, which is part of Notebooks.

Markdown can serve as viable alternative to Notebooks‘ formatted documents for a couple of reasons:

Portability: Markdown files are plain text, so they are smaller in size and easy to transfer across platforms and devices.
Readability: Even the plain text version is perfectly readable in its unrendered form.
Conversion: Markdown can be converted to HTML, PDF, and other formats, making it versatile for different uses. Conversion happens “on the fly”, which keeps formatting issues from creeping in.
Simplicity: Markdown is easy to learn and use.
Support: Many applications and tools support Markdown, so it is becoming a widely adopted standard for creating and sharing content.

A few specific use cases and examples:

Authors and writers use Markdown to create articles, blog posts, and other forms of written content because of its simplicity and ease of use.
Markdown is ideal for creating technical documentation and user guides, allowing for clear and structured presentation. (The document you are reading just now was created in Markdown as well).
Markdown is commonly used to write web content that can be easily converted to HTML for publishing online.

Markdown Filename Extensions

Although Markdown documents are regular plain text documents, it is common to assign a specific filename extension, which allows dedicated applications to treat them accordingly. The most common extension is .md, but you may also see .markdown, .text, .mdown or even .rmd. Notebooks handles all of these filename extensions as Markdown.

Markdown Syntax

The Markdown reference guide is available as a separate chapter.

Markdown Documents in Notebooks

By default, Notebooks displays Markdown documents with a dedicated icon, which makes them easy to identify in the list. If you set Notebooks to use thumbnail images for documents and a Markdown document contains an image, Notebooks uses that image instead.

Create Markdown Documents

To create a new Markdown document, just select Markdown from any of the + menus. Notebooks creates a new document with filename extension .md, presents its regular plain text editor and you can start writing.

On your iPhone or iPad

Especially on an iPhone or iPad, Notebooks tries to keep the interface clean and hide options until you need and activate them. This is why the + menu does not show Markdown by default. In Notebooks‘ Settings > Write and Edit > Markdownyou can turn on the switch Use Markdown as Extra Document Type to make Markdown available from the + menu.

You could also rename a .txt document to .md to turn it into a Markdown document. This is what Notebooksdoes when you duplicate a text document to Markdown.

View Markdown Documents

When you open a Markdown document, Notebooks by default displays its formatted version by converting it to HTML on the fly, with current settings and attributes. So the Markdown document looks like a formatted document when you open it.

If you prefer to open Markdown documents in their plain text version, you can change Notebooks‘ default behavior in Settings > Write and Edit > Markdown by turning off Open Markdown documents in formatted view.

Edit Markdown Documents

Editing Markdown documents slightly varies depending on whether Notebooks opens them as plain text or in their rendered version. Let’s look at each option separately.

Open Markdown as Plain Text

If Notebooks is set to open Markdown documents as plain text, tap or click the text to activate the cursor and start writing in Notebooks‘ plain text editor.

Open Markdown as Formatted Text

If Notebooks opens Markdown documents in their formatted version, however, you can tap or click the position in the formatted text where you want to start editing. Notebooks switches to the plain text version and tries to place the cursor at the selected position, so you can start writing. In some cases Notebooks may be unable to identify your tap or click position and only switches to plain text; you then need to tap or click the text again to start editing.

When Notebooks cannot find the correct position, it may be due to trailing spaces at the end of lines with the setting Make every newline a Line Break active. Removing the two spaces or changing setting can resolve this.

When you are done editing and hide the keyboard or type cmd-return on an external keyboard, Notebooks switches back to the—now updated—formatted view.

Editing at the tapped/clicked position in the formatted text is optional, and you can toggle this feature in Notebooks‘ Settings > Write and Edit (Editing) > Markdown. When this feature is off, you have other options to switch to plain text:

On a keyboard, type cmd-return to toggle between formatted and plain text view.
On a Mac, click the Toggle View button in the top right corner.
On an iPhone or iPad, tap the formatted text to switch to plain text version. Dismissing the keyboard then automatically switches back to the formatted view.

View Plain Text and Formatted Text Side by Side

Although Markdown has been invented to separate content from layout and support distraction free writing, it is a common habit to regularly check the rendered text while working on the Markdown text. In Notebooks on an iPad or Mmac, you don’t necessarily need to switch between these versions, which would clearly interrupt your writing flow, but instead you can open the same document in separate windows or views.

On your iPad

With your iPad in landscape orientation, open your document as usual, and it appears in the right frame. Then tap and hold the document again in the list, and from the popup menu choose 2UP. Notebooks opens the same document in the left frame. Now you have two views of the same document, and when you start editing one of them, the other updates whenever you stop typing. – This gives you a live preview of the rendered Markdown document.

On your Mac

The options are even more flexible in Notebooks for Mac. As you edit a Markdown document, type shift-cmd-return to open the current document in a separate window. You can position the window side by side or one above the other, and as you edit the Markdown text in one window, you can view the rendered version in the other. – The second window automatically updates when Notebooks saves your changes or when you switch between windows or apps.

Keyboard Shortcuts

Markdown rules are simple and easy to memorize, but typing the required character sequences may become tedious over time. To simplify Markdown editing, Notebooks offers a series of keyboard shortcuts and extra keyboard keys, which make writing Markdown swift and convenient. So rather than enclosing a phrase with ** to mark it as bold, for example, you can select the phrase and type cmd-B or, on an iPhone or iPad, use the extra key B to add or remove the corresponding formatting characters.

For a complete list of shortcuts, please refer to keyboard shortcuts and extra keyboard keys.

Text Alignment and Syntax Highlighting

To enhance reading and writing Markdown, Notebooks provides options to highlight Markdown syntax and align plain Markdown text. This ensures that lists are well-organized and indented, headings stand out clearly, bold and italic text have distinct formatting, and links, footnotes, and citations are easy to spot. This not only improves readability, it also allows you to quickly identify incorrectly applied syntax.

The option to highlight Markdown syntax is inactive by default, but you can activate it in Notebooks‘ Settings > Write and Edit > Markdown > Highlight Markdown Syntax.

Convert Documents to Markdown

Maybe you have a collection of text documents that you wish to continue editing in Markdown, or you may have previously worked with formatted documents but want to switch to Markdown. In any case, Notebooks makes it easy to convert between formats anytime, and switching to Markdown is easy.

The most general option is to use Duplicate as… Markdown from a document’s action menu or from the document list’s context menu. This option is available for all document types that Notebooks can convert directly to Markdown, and the result is a duplicate of the selected document, handled as Markdown.

The conversion from plain text and formatted text provides a few more options.

Preview Plain Text as Markdown

Maybe you just want to preview a plain text document as Markdown, without actually converting it and creating a duplicate.

On your Mac

Just type cmd-return or click the Toggle View button for an instant Markdown preview; you can use the same to return to normal view.

On your iPhone and iPad

Tap the current document’s title and choose Format Document… from the menu. Notebooks presents a preview of the converted document, with a series of options reachable from the toolbar. Choosing Treat as Markdown saves the document as Markdown, but without duplicating it.

Turn Plain Text to Markdown by Changing Filename Extensions

Markdown files are saved as plain text, but with .md as file extension. So a shortcut for converting plain text documents to Markdown is to open the document’s info and append .md to its title, replacing .txt if necessary. Notebooks renames the document from .txt to .md and handles it as Markdown from now on. – The conversion works in the opposite direction as well, of course.

Paste Formatted Text as Markdown

If you do not want to convert an entire formatted document, but instead copy a section of a formatted document into a Markdown document, you can use use Notebooks‘ capabilities of turning HTML to Markdown (markdownify is the term for that):

Copy a section of a formatted document, a web page, or text from another app.
Open a Markdown document and choose Paste as Markdown or use the keyboard shortcut ⌥⌘V.
Notebooks converts the formatted text you have copied to Markdown, doing its best to preserve all formatting info, and inserts the result into the target document.

Convert Markdown Documents to Other Formats

Just as you can convert document to Markdown, Notebooks allows you to turn Markdown documents to other formats as well. All options are available in the Duplicate as… sub menu of the document’s action menu and the document list’s context menu.

Conversion to plain text and formatted document may be straight forward by now, but Notebooks provides other options as well:

LaTeX: Converts the Markdown text to LaTeX and saves the result as .tex file´, which is plain text, too. You can further process the result in your favorite LaTeX compiler like MacTeX or Overleaf, to name just two.
RTF: The result is a regular .rtf document, but it is not editable in Notebooks.
ODT: Can be opened and edited in MS Word and open source applications like OpenOffice or LibreOffice. This option is available in Notebooks for Mac only.
Word Document: This option is available in Notebooks for Mac only.

Markdown Specific Settings

Notebooks offers a variety of settings to manage and customize the handling and display of Markdown documents. They are available in Notebooks Settings > Write & Edit > Markdown (Settings > Editing > Markdown on a Mac); some of the plain text specific settings are useful for Markdown editing as well.

Notebooks’ Combined Markdown

Markdown documents are plain text, which makes them compact and easy to share. Notebooks opens and displays these documents in their rendered version, so they appear as perfectly formatted documents. However, when viewed outside of Notebooks or another Markdown-compatible app, they still appear as plain text. So when you send a Markdown document to someone else, the recipient will just see the plain text version; the same happens when you preview a Markdown document in macOS Finder. – So it seems challenging to create and edit documents in Markdown, but consistently display them as formatted text outside of Notebooks.

This is where Notebooks‘ Combined Markdown comes into play: when you choose to save Markdown documents as Combined Markdown, Notebooks saves plain text and formatted text in a single HTML document. The document appears as a formatted text by default, but Notebooks can still edit it as Markdown, because the plain text is embedded in the file.

Combined Markdown is an option designed for special use cases and requirements, so we recommend carefully considering if you need this feature before activating it.
To start using combined Markdown, go to Notebooks’ Settings > Write and Edit > Markdown and turn on the switch Convert to combined Markdown (.html). From then on, Notebooks saves all new Markdown documents as combined Markdown.
On your iPhone or iPad you have the option to convert existing regular Markdown documents to combined Markdown the next time you edit them.
When you open a combined Markdown document, Notebooks retrieves the plain Markdown text and converts it on the fly, applying your current settings. If the result differs from the saved HTML, Notebooks saves an updated version of the document, preserving its current modification date.

In Notebooks, you won’t notice any difference between regular and combined Markdown documents except for the slightly different document icon.

How Notebooks Saves Combined Markdown

Notebooks stores plain Markdown text as Plain Text Representation in a comment at the top of the generated HTML document. Here is an example:

<-- Plain Text Representation       << comment tag
# My *Markdown* Document
This is the plain Markdown.
-->                                 << comment tag

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

There are two important facts to keep in mind:

When opening combined Markdown document, Notebooks always retrieves the Plain Text Representation and rebuilds the formatted version on the fly. So Notebooks picks up any changes in the Plain Text Representation.
As the formatted text is regenerated on the fly, Notebooks ignores and overwrites any changes that may have been made to the formatted text.

Edit Combined Markdown

When Notebooks saves a combined Markdown document, it saves an HTML version of your text and includes the Plain Text Representation as an invisible comment. When you reopen the document for editing, Notebooks retrieves the Plain Text Representation and presents it for your to edit. This process is seamless and you won’t notice any difference compared to regular Markdown editing.

When editing combined Markdown documents in other applications, there are a few recommendations you should follow.

Edit the combined Markdown document as plain text, not as HTML or formatted text.
When editing, you may delete the comment tags and/or the HTML code, just leaving the plain Markdown text. The next time you open the document in Notebooks, the HTML version will be updated automatically.
If you do not delete the comment tags, please do not modify them, either; just leave them as first and last line of your text.
Changes you make to the HTML code of the document will be ignored and overwritten.

FAQ

How to Use Mermaid in Markdown

With Mermaid you can create charts and diagrams with just a few simple text commands. Mermaid perfectly integrates with Markdown, so it is very easy to embed Mermaid charts into Notebooks documents.

When embedding a Mermaid diagram in Markdown, make sure to enclose it in a fenced code block. This declares that the contained text is Mermaid code. Here is an example:

```mermaid
graph TD;
	A-->B;
	A-->C;
	B-->D;
	C-->D;
```

The leading and trailing backticks ``` form the code block, mermaid on the first line indicates that the contained code should be interpreted as Mermaid code, and everything in between is the actual Mermaid code.

There is one more hint: when copying Mermaid code and pasting it into a document, iOS or macOS may convert some of the characters to their smart counterparts. This could turn -- into –, for example, which invalidates the Mermaid code. So if you encounter any issues, watch out for these smart characters.

...

How to Disable Typographic Quotes

Use Mathematic Expressions in Documents (MathJax or KaTeX)

MathJax and KaTeX are display engines for complex mathematic formulas, and Notebooks supports both in combination with Markdown. The simplest option to use MathJax or KaTeX is by selecting one of Notebooks‘ pre-installed document themes which include all the necessary scripts (Scientific+MathJax and Scientific+Katex).

Alternatively you can add the required scripts at the bottom of your favorite document style sheet (right after the </style> tag), or you simply add these lines at the top of a Markdown document.

For MathJax, use

<script>
MathJax = {
    tex: {
        inlineMath: [ ['$','$'], ['\\(','\\)'] ],
        displayMath: [ ['$$','$$'], ['\\[','\\]'] ],
        processEscapes: true
    }
};
</script>

The definitions of inlineMath and displayMath control the way you enter your mathematical expressions. Our default implementations include single parentheses as well, which is very convenient but may also produce unexpected results. If you don’t want the single parentheses, you can use the definition above.

For KaTeX, use the following, again in your favorite document theme or in the header/footer of a Markdown document, as documented at katex.org:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css" integrity="sha384-nB0miv6/jRmo5UMMR1wu3Gz6NLsoTkbqJghGIsx//Rlm+ZU03BU6SQNC66uf4l5+" crossorigin="anonymous">

<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.js" integrity="sha384-7zkQWkzuo3B5mTepMUcHkMB5jZaolc2xDwL6VFqjFALcbeS9Ggm/Yr2r3Dy4lfFg" crossorigin="anonymous"></script>

<script defer src="https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/contrib/auto-render.min.js" integrity="sha384-43gviWU0YVjaDtb/GhzOouOXtZMP/7XUzwPTstBeZFe/+rCMvRwr4yROQP43s0Xk" crossorigin="anonymous"
    onload="renderMathInElement(document.body);"></script>

...

Can I Use a Different Markdown Engine?