The Markdown Guide

The source repository for The Markdown Guide book is available for reference. You can purchase the physical or digital book through the following platforms:

• Gumroad
• LeanPub
• Amazon

For every syntax element in the basic and extended syntax chapters, the book provides three distinct views to help you understand the conversion process:

1. Markdown: The raw text you type into your editor.
2. HTML: The underlying HTML code generated by the Markdown processor.
3. Rendered Output: The final visual result seen by the reader.

There is no single universal standard for Markdown; instead, different applications implement different versions known as flavors.

Think of flavors as language dialects. While the core syntax is similar, one application might support extended syntax elements that another does not. When choosing a tool, check its documentation to see which flavor it implements to ensure your files remain portable and compatible with other tools.

The book uses specific icons to denote supplemental information:

• Asides: Indicated by an i icon. Used for extra helpful information.
• Tips: Indicated by a key icon. Used for useful tricks or shortcuts.

When Markdown or HTML code samples in the book wrap to a new line, a backslash (\) is displayed at the end of the first line.

Note: The \ is not part of the actual code; it is a visual indicator that the next line is a continuation of the current line.

Markdown is a lightweight markup language used to add formatting to plaintext documents. Unlike WYSIWYG (What You See Is What You Get) editors like Microsoft Word, you add syntax directly to the text to indicate formatting.

Core Workflow:

1. Create: Write text in a text editor or Markdown application. Save files with .md or .markdown extensions.
2. Process: A Markdown processor (or parser) takes the plaintext and converts it into HTML.
3. View/Output: The resulting HTML can be viewed in a web browser, styled with CSS, or converted to other formats like PDF.

# Heading One

**this text is bold**

Formatting

You can use links, code (inline backticks only), and emphasis inside table cells. You cannot use headings, blockquotes, lists, horizontal rules, images, or raw HTML tags.

Escaping Pipes

To display a literal pipe character (|) inside a table cell, use the HTML character code |.

| Column 1 | Column 2 |
| -------- | -------- |
| Text     | Use | to show a pipe |

To create an unordered list, add dashes (-), asterisks (*), or plus signs (+) in front of line items. All three delimiters produce the same HTML <ul> output.

Best Practice: Do not mix different delimiters (e.g., using both - and *) within the same list to ensure compatibility across different Markdown parsers.

Handling Numbers: If you need to start an unordered list item with a number followed by a period (e.g., a year), escape the period with a backslash (\) to prevent it from being interpreted as part of a list structure.

- First item
- Second item
- Third item
- Fourth item

* First item
* Second item
* Third item
* Fourth item

+ First item
+ Second item
+ Third item
+ Fourth item

- 1968\. A great year!
- I think 1969 was second best.

Markdown can be used to create slideshows more quickly than traditional presentation software.

Tools:

• Browser-based: Remark, Cleaver, and Marp.
• Mac Applications: Deckset and Hyperdeck.

There are two primary methods for adding emoji to Markdown files:

1. Copy and Paste: Copy an emoji from a source (like Emojipedia) and paste it directly into your text. Most modern Markdown applications and exported formats (HTML/PDF) support this.

   • Tip: If using a static site generator, ensure your HTML pages are encoded as UTF-8.

2. Emoji Shortcodes: Some applications support shortcodes wrapped in colons (e.g., :emoji-name:).

Note: Shortcode support varies by application.

Gone camping! :tent: Be back soon.

That is so funny! :joy:

To indicate that text should be crossed out, wrap the words in two tilde symbols (~~).

The world is ~~flat~~ round.

Many Markdown processors automatically convert plain text URLs (e.g., http://example.com) into clickable links without requiring explicit link syntax.

Disable automatic linking

To prevent a URL from being automatically turned into a link, wrap the URL in backticks to denote it as code.

# Automatically linked
http://example.com

# Not linked (as code)
`http://www.example.com`