Markdown

A Guide to Writing and Formatting Technical Documentation¶

In this chapter you will learn how to write code in Python and text to keep it in technical documentation Markdown.

After this section, it should be clear to you:

• How to operate directly using the syntax of Markdown tags or the editor’s GUI mode,
• How to clearly document data analysis,
• How to convert notebooks to MD in the terminal.

Markdown is a simple markup language. It makes it easy to convert text into valid HTML code. Markdown is used to create memos, technical documentation, in instant messaging, online forums and more.

Markdown is a convenient way to create formatted text using a simple syntax. There are different flavors of markdown, but the basics are supported in all cases and generally cover 80% of use cases. HTML is also correct in markdown cells. In fact, all the text and header of this notebook is markdown/HTML. With markdown you can create headings, embed images, link to other pages, create lists and more.

Markdown is often used to create documantation for software projects. It is used to describe code repositories on the popular GitHub site, add instructions for users and other important information.

Markdown is also used by popular services and blog pltforms such as Medium, Ghost or Jekyll.

Other uses include applications for creating notes and to-do lists (and. to do lists). Markdown is also used by popular instant messaging and collaboration tools such as Slack or Trello.

• 2004: John Gruber developed Markdown.
• 2014: CommonMark was established as a standard Markdown specification to resolve inconsistencies and ambiguities in Markdown implementations. This initiative was started by John MacFarlane and supported by other Markdown enthusiasts to provide a reliable and consistent specification.

This guide will provide you with a comprehensive understanding of the key commands in GitHub Flavored Markdown (GFM), a strict oversight of CommonMark.

Philosophy¶

Markdown is supposed to be as easy to read and write as possible.

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as plain text, without appearing to be marked up with markup or formatting instructions. While Markdown syntax has been influenced by several existing text filters for HTML - including Setext, atx, Textile, reStructuredText, Grutatext and EtText - the biggest source of inspiration for Markdown syntax is the plain-text email format.

To that end, Markdown syntax consists entirely of punctuation marks, which have been carefully selected to look like what they mean. For example, asterisks around a word look like underline. Markdown lists look like, well, lists. Even block quotes look like quoted text fragments, assuming you’ve ever used email.

Markdown as HTML¶

Markdown is not a replacement for HTML, nor is it even close to it. Its syntax is very simple and corresponds to only a very small subset of HTML markup. The idea is not to create a syntax that makes it easier to insert HTML markup. In my opinion, HTML markup is already easy to insert. The idea of Markdown is to make prose easier to read, write, and edit. HTML is a publishing format; Markdown is a writing format. Therefore, the Markdown formatting syntax applies only to things that can be conveyed in plain text.

For any markup that is not covered by Markdown syntax, simply use HTML. There is no need to precede or delimit it to indicate that you are switching from Markdown to HTML; you simply use tags.

The only restrictions are that block-level HTML elements - e.g. <div>, <table>, <pre>, <p>, etc. - must be separated from the surrounding content by blank lines, and that block start and end tags should not be indented with tabs or spaces. Markdown is smart enough not to add extra (unwanted) <p> tags around block-level HTML tags.

For example, to add an HTML table to a Markdown article:

This is a regular paragraph.

<table>
<tr>
<td>Foo</td>
</tr>
</table>

This is a regular paragraph.

Special Characters¶

There are two characters in HTML that require special treatment: < and &. Left angle brackets are used to start tags; ampersands are used to denote HTML entities. If you want to use them as literal characters, you have to escape them as entities, e.g. < and &.

Ampersands are particularly troublesome for web authors. If you want to write about “AT&T,” you have to write “AT&T.” Ampersands must even be avoided in URLs. So, if you want to link to:

http://images.google.com/images?num=30&q=larry+bird

you should encode the URL as:

http://images.google.com/images?num=30&q=larry+bird

in the href attribute of the anchor tag. Needless to say, this is easy to forget and is probably the most common source of HTML validation errors in well-marked web pages.

Markdown allows you to use these characters in a natural way, taking care of all the necessary escaping. If you use an ampersand as part of an HTML entity, it will remain unchanged; otherwise, it will be translated to &.

So if you want to put a copyright symbol in your article, you can write:

© which is ©

and Markdown will leave it alone. But if you write:

AT&T

Markdown will translate that to:

AT&T

Similarly, because Markdown supports inline HTML, if you use angle brackets as delimiters for HTML tags, Markdown will treat them as such. But if you write:

4 < 5

Markdown will translate that to:

4 < 5

However, inside Markdown code spans and blocks, angle brackets and ampersands are always encoded automatically. This makes it easier to use Markdown to write HTML code. (Unlike raw HTML, which is a terrible format for writing HTML syntax, because every single < and & in the example code has to be escaped.)

Block elements¶

Paragraphs¶

A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line - a line containing only spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.

The “one or more consecutive lines of text” rule means that Markdown supports “hard-wrapped” text paragraphs. This is very different from most other text-to-HTML formatters (including Movable Type’s “Convert Line Breaks” option), which translate each line break in a paragraph to a <br /> tag.

To insert a <br /> break using Markdown, you end the line with two or more spaces, then type return.

Yes, it takes a bit more effort to create <br />, but the simplified rule "every line break is <br /> would not work in Markdown. Email-style blockquoting and multi-paragraph lists in Markdown work best - and look better - when you format them with hard breaks.

Headings¶

Markdown supports two heading styles, Setext and atx.

Setext-style headings are “underlined” using equal signs (for first-level headings) and dashes (for second-level headings). For example:

This is H1
=============

This is H2
-------------

Any number of underscores = or - will work.

Atx-style headings use 1-6 hash characters at the beginning of the line, corresponding to heading levels 1-6. For example:

# This is H1

## This is H2

##### This is H6

Optionally, you can “close” atx-style headings. This is purely cosmetic - you can use this if you think it looks better. The closing hashes don’t even have to match the number of hashes used to open the header. (The number of opening hashes determines the header level):

# This is H1 #

## This is H2 ##

### This is H3 ######

Quotes¶

Markdown uses email-style > characters for blockquotes. If you’re familiar with quoting sections of text in an email, you know how to create a blockquote in Markdown. It looks best when the text is tightly wrapped and placed > before each line:

This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisz, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Markdown lets you be lazy and place > only before the first line of a tightly wrapped paragraph:

This is a two paragraph block quote. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim hanging, viverra nec, fringilla in, laoreet vitae, risus.

Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

Blockquotes can include other Markdown elements, including headings, lists, and code blocks:

This is a heading.¶

1. This is the first item in the list.
2. This is the second item in the list.

Here’s some sample code: return shell_exec(“echo $input |$markdown_script”);

Any decent text editor should make it easy to quote in an email-style way.

Lists¶

Markdown supports ordered (numbered) and unordered (bulleted) lists.

Unordered lists use asterisks, pluses, and dashes - interchangeably - as list markers:

• Red
• Green
• Blue

is equivalent to:

• Red
• Green
• Blue

and:

• Red
• Green
• Blue

Ordered lists use numbers followed by periods:

1. Bird
2. McHale
3. Parish

It is important to note that the actual numbers used to denote the list have no effect on the HTML output produced by Markdown. The HTML that Markdown creates from the list above is:

1. Bird

2. McHale

3. Parish

If you were to instead write the list in Markdown like this:

1. Bird
2. McHale
3. Parish

or even:

3. Bird
4. McHale
5. Parish

you would get exactly the same HTML output. The idea is that if you want, you can use ordinal numbers in your Markdown ordered lists so that the numbers in the source match the numbers in the published HTML. But if you want to be lazy, you don’t have to.

However, if you use lazy list numbering, you should still start the list with the number 1. At some point in the future, Markdown may support starting ordered lists with any number.

List tags usually start at the left margin, but can be indented by up to three spaces. List tags must be followed by at least one space or tab.

* This is an unordered list
* It is useful for many things 
* Grocery lists 
* Plans to take over the world 
* Large plans may require multiple lists

• This is an unordered list
• It is useful for many things
• Grocery lists
• Plans to take over the world
• Large plans may require multiple lists

1. Create an ordered list 
1. Use numbers 
1. Let the computer handle numbering 
1. Look super organized
1. Take over the world

1. Create an ordered list
2. Use numbers
3. Let the computer handle numbering
4. Look super organized
5. Take over the world

To make the letters look nice, you can wrap elements with hanging indents:

• Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
• Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

But if you want to be lazy, you don’t have to:

• Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
• Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id sem consectetuer libero luctus adipiscing.

List items can consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by 4 spaces or one tab:

1. This is a list item with two paragraphs. Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.

Vestibulum enim wisz, viverra nec, fringilla in, laoreet vitae, risus. Donec sit amet nisl. Aliquam semper ipsum sit amet velit.

2. Suspendisse id sem consectetuer libero luctus adipiscing.

It looks nice to indent each line of subsequent paragraphs, but Markdown lets you be lazy here too:

• This is a list item with two paragraphs.

This is the second paragraph in a list item. On the page only the first line needs to be indented. Lorem ipsum dolor sit amet, consectetuer adipiscing elit.

• Another item in the same list.

To place a block quote inside a list item, > the block quote delimiters must be indented:

• List item with block quote:

This is a block quote inside a list item.

To place a code block inside a list item, the code block must be indented twice - 8 spaces or two tabs:

• List item with code block:

It is worth noting that it is possible to accidentally invoke an ordered list by writing something like:

1986. What a great season.

In other words, the sequence digit-period-space at the beginning of the line. To avoid this, you can insert a period with a backslash:

1986. What a great season.

Code Embedding¶

Preformatted code blocks are used to write about programming or markup source code. Instead of creating normal paragraphs, the lines of a code block are interpreted literally. Markdown encloses the code block in <pre> and <code> tags.

To create a code block in Markdown, simply indent each line of the block by at least 4 spaces or 1 tab. For example, given this input:

this is code

This is a normal paragraph:

This is a code block.

Markdown will generate:

This is a normal paragraph:

This is a code block.

One level of indentation - 4 spaces or 1 tab - is removed from each line of the code block. For example, this:

Here is an AppleScript example:

tell application “Foo” beep end tell

will become:

Here is an AppleScript example:

tell application "Foo"
beep
end tell

The code block continues until it reaches a line that is not indented (or the end of the article).

Horizontal Rules¶

A horizontal rule tag (<hr />) can be created by placing three or more dashes, asterisks, or underscores on a single line. You can use spaces between the dashes or asterisks if you wish. Each of the following lines will create a horizontal rule:

* * *

***

*****

- - -

---------------------------------------

Links¶

Markdown supports two link styles: inline and reference.

In both styles, the link text is delimited by [square brackets].

To create an inline link, use a set of regular brackets immediately after the closing square bracket of the link text. Inside the brackets, place the URL you want the link to point to, along with an optional title for the link, surrounded by quotation marks. For example:

This is an [an example](http://example.com/ “Title”) inline link.

This link does not have a title attribute.

This will produce:

This is an

example inline link.

This link does not have a title attribute.

If you are referencing a local resource on the same server, you can use relative paths:

See About for details.

Reference-style links use a second set of square brackets, inside which you place a label of your choice to identify the link:

This is an example link in the reference style.

Optionally, you can use spaces to separate the sets of brackets:

This is an example link in the reference style.

Then, anywhere in the document, you can define a link label as follows, on a separate line:

That is:

Square brackets containing the link identifier (optionally indented from the left margin using up to three spaces);

• followed by a colon;
• followed by one or more spaces (or tabs);
• followed by the URL of the link;
• optionally followed by the link’s title attribute, enclosed in double or single quotes or enclosed in parentheses.

The following three link definitions are equivalent:

[foo]: http://example.com/ "Optional Title Here"
[foo]: http://example.com/ 'Optional Title Here'
[foo]: http://example.com/ (Optional Title Here)

The default link name shortcut allows you to omit the link name, in which case the link text itself is used as the name. Simply use an empty set of square brackets - for example, to link the word “Google” to google.com, you would simply write:

Google

Then define the link:

Because link names can contain spaces, this shortcut works even with multiple words in the link text:

Visit Daring Fireball for more information.

Then define the link:

Link definitions can be placed anywhere in a Markdown document. I usually place them immediately after each paragraph in which they are used, but if you want, you can place them all at the end of the document, similar to footnotes.

Here’s an example of referral links in action:

I get 10x more traffic from Google [1] than from [Yahoo] [2] or [MSN] [3].

[1]: http://google.com/ "Google" [2]: http://search.yahoo.com/ "Yahoo Search" [3]: http://search.msn.com/ "MSN Search"

Highlights¶

Markdown treats asterisks (*) and underscores (_) as underlining indicators. Text wrapped in a single * or _ will be wrapped in the HTML tag <em>, double * or _ will be wrapped in the HTML tag <strong>. For example, this input:

*single asterisks*

_single underscores_

**double asterisks**

__double underscores__

will generate:

single asterisks

single underscores

double asterisks

double underscores

You can use any style you like; the only restriction is that the same character must be used to open and close the underline range.

An underscore can be used in the middle of a word:

unfriggingbelievable

But if you surround * or _ with spaces, it will be treated as a literal asterisk or underscore.

To create a literal asterisk or underscore where it would otherwise be used as an underscore separator, you can escape the backslash:

*this text is surrounded by literal asterisks*

Code¶

To indicate a range of code, wrap it in double quotes (`). Unlike a preformatted code block, a code range indicates code in a normal paragraph. For example:

Use the printf() function.

will generate:

Use the printf() function.

To include a literal backtick in a span of code, you can use multiple backticks as opening and closing delimiters:

This is a single backtick (`) here.

which produces the following result:

This is a single backtick (`) here.

The backtick delimiters surrounding a span of code can contain spaces - one after the opening one, one before the closing one.

This allows literal backticks to be placed at the beginning or end of a code span:

A single backtick in a code span:

A backtick-delimited string in a code span: `foo`

will result in:

A single backtick in a code span: `

A backtick-delimited string in a code span: `foo`

In the case of code span, ampersands and angle brackets are automatically encoded as HTML entities, making it easy to include sample HTML tags. Markdown will turn this into:

Please don’t use any <blink> tags.

into:

<p>Please don't use any <code>&lt;blink&gt;</code> tags.</p>

You could write this:

— is the decimal equivalent of —.

to get:

<p><code>&amp;#8212;</code> is the decimal equivalent of <code>&amp;mdash;</code>.</p>

Images¶

It is admittedly quite difficult to develop a “natural” syntax for embedding images in a plain text document.

Markdown uses an image syntax that is intended to resemble the syntax of links, allowing for two styles: inline and reference.

The inline image syntax looks like this:

![Image description](p4ds.png)

![Image description](p4ds.png "Optional title")

That is:

An exclamation mark: !

• followed by a set of square brackets containing the alt attribute text for the image;
• followed by a set of brackets containing the URL or path to the image and an optional title attribute enclosed in double or single quotes.

The syntax for an image reference style is as follows:

![Optional title][id]

Where “id” is the name of a defined image reference. Image references are defined using syntax identical to link references:

[id]: p4ds.png "Optional title"

At the time of writing, Markdown does not have a syntax for specifying image dimensions; if that is important to you, you can simply use the regular HTML <img> tags.

Tables¶

Creating tables is awful in HTML. Markdown (or rather multi-markdown) creates really good looking tables with simple text entry.

| Date | Max Temp | Min Temp |
| :---: | :---: | :---: |
| 4/12 | 75       | 65       |
| 4/13 | 80       | 68       |
| 4/14 | 68       | 50       |

Equations¶

Notebooks support MathJax, so using a subset of the $\LaTeX$ syntax, you can easily render complex equations in notebook cells. We don’t have time to go into the details of the syntax, but you can find many tutorials on the subject. Showing a few examples will give you an idea though!

To put equations inline with text, put them in $, to put them on separate lines, put them in $$.

Let’s start with a simple example, Newton’s Second Law:

$$F = m a$$

We can also compose much more complicated equations with a bit more syntactic effort:

$$\left( \frac{Dv}{Dt} \right) = -2 \Omega u \text{sin}\phi - \frac{u^2}{a} \text{tan}\phi$$

$$\frac{\partial\zeta}{\partial t} = - V \cdot \nabla(\zeta + f) - \omega \frac{\partial \zeta}{\partial p}
- (\zeta + f) \nabla \cdot V + k \cdot \left(\frac{\partial V}{\partial p} \times \nabla \omega \right)$$

Sample operators / functions¶

Special characters / Symbols¶

Latin¶

No dot¶

\imath $\rightarrow$ $\imath$, \jmath $\rightarrow$ $\jmath$

Hat¶

\hat{\imath} $\rightarrow$ $\hat{\imath}$, \hat{\jmath} $\rightarrow$ $\hat{\jmath}$

Greek letters¶

Capital¶

Lowercase¶

Other¶

Other symbols¶

Relational Symbols¶

Binary operators¶

Cumulative operators¶

Named operators¶

Recommended¶

To help you even more in learning how to create technical documents with Markdown here is a list of recommended sources and cheat sheets:

• [Markdown Cheat Sheet](markdown-cheatsheet.pdf)
• Markdown Guide
• Very nice equation generation in Latex for beginners

Converting to MD¶

Documents of all types can be converted to MD using the nice-to-use ‘nbconvert’ function. Home page of the package - here.

Using the converter comes down to writing in the terminal:

$ jupyter nbconvert --to FORMAT notebook.ipynb

Also check out the tutorial below:

Useful¶

1. Create a table of contents in Markdown - binarytree, github-markdown-toc
2. Create an empty table in Markdown - Tablesgenerator
3. Convert Excel to Markdown table - Tableconvert
4. Markdown preview for Sublime Text 3 - Packagecontrol
5. Markdown preview for Visual Studio Code - Markdown Preview Enhanced
6. A collection of useful Markdown tools - Awesome Markdown
7. Markdownlint - markdownlint, markdownlint-cli2, markdownlint-cli2-action, vscode-markdownlint
8. Lightweight Python tools for converting various files to Markdown - Markitdown
9. SSE MCP server to call MarkItDown - MarkItDown-MCP

Check out the official documentation on GitHub to learn more about writing and formatting syntax. You can also check out the latest Markdown updates and features by visiting GitHub changelog posts.