The ultimate guide to markdown

This guide covers everything you need to know about Markdown, from basic syntax that works everywhere to advanced features supported by popular platforms. Whether you're writing documentation, drafting blog posts, or crafting messaging in Knock, you'll learn how to create well-formatted content with just plain text.

Introduction to Markdown

What is Markdown?

Markdown is a lightweight markup language that uses simple, intuitive syntax to format plain text documents. Created by John Gruber in 2004, it allows writers to add formatting elements like headings, bold text, and links using regular keyboard characters rather than complex HTML tags or relying on a formatting toolbar.

When you write in Markdown, you're creating a plain text file that's both human-readable in its raw form and easily convertible to formatted HTML for web display.

The genius of Markdown lies in its simplicity and readability. Unlike HTML where <h1>This is a heading</h1> creates a heading, Markdown uses # This is a heading to achieve the same result. This approach means your source documents remain clean and easy to read, even without rendering.

Why use Markdown?

There are many reasons why so many platforms support Markdown:

• Portability. Markdown files are plain text, which means they can be opened and edited in any text editor on any operating system without compatibility issues or proprietary software requirements.
• Version control friendly. Plain text files work seamlessly with Git and other version control systems, making it easy to track changes, collaborate with others, and manage documentation alongside code.
• Fast and focused writing. Without the distractions of formatting toolbars and style options, writers can concentrate on their content and add formatting as they type using simple keyboard shortcuts.
• Universal adoption. Major platforms like GitHub, Reddit, Stack Overflow, and Discord all support Markdown. Other platforms, like Slack, have created their own variation of markdown, making it a valuable skill that transfers across different tools and communities.

How does Markdown work

Markdown works through a two-step process that transforms your plain text into formatted output. When you write Markdown syntax, a parser reads your text file and identifies the special characters and patterns that indicate formatting. The parser then converts these patterns into HTML tags, which browsers and other applications can display with proper formatting.

For example, when you type **bold text**, the Markdown parser recognizes the double asterisks as indicators for strong emphasis and converts them to <strong>bold text</strong>. Most modern applications handle this conversion automatically and in real-time, showing you a preview of the formatted output while you type.

Core components of Markdown

The structure of Markdown revolves around a small set of formatting rules that cover the most common text formatting needs:

• Structural elements. Headings, paragraphs, and lists form the backbone of any document and Markdown provides simple syntax for each.
• Inline formatting. Bold, italic, and code formatting can be applied to specific words or phrases within your text using surrounding characters.
• Links and references. Markdown supports both inline links and reference-style links, making it easy to include hyperlinks without cluttering your text.
• Block-level elements. Blockquotes, code blocks, and horizontal rules help organize and separate different sections of your content.
• Media embedding. Images can be embedded using syntax similar to links, and many Markdown processors support additional media types.

Common Markdown use cases

In particular, Markdown works great for the following use cases:

• Email and messaging. Many messaging tools like Knock support Markdown formatting, allowing users to add structure and style to their messages without switching contexts.
• Documentation and README files. Nearly every software project uses Markdown for documentation because it's readable in source control, easy to maintain, and renders beautifully on platforms like GitHub.
• Technical blogging and writing. Many static site generators and content management systems support Markdown, allowing writers to create blog posts and articles without dealing with HTML.
• Note-taking and knowledge management. Applications like Obsidian, Notion, and Bear use Markdown as their core format, enabling users to create interconnected notes with consistent formatting.
• Academic and scientific writing. Markdown can be extended with tools like Pandoc to support citations, footnotes, and complex formatting while maintaining the simplicity of plain text authoring.

Basic Markdown syntax

Paragraphs

Creating paragraphs in Markdown follows the natural flow of writing. Simply type your text, and when you want to start a new paragraph, press “Enter” twice to create a blank line between paragraphs. Single line breaks within a paragraph are typically ignored, allowing you to wrap long lines in your text editor without affecting the output.

If you need to force a line break within a paragraph without starting a new one, add two spaces at the end of a line before pressing “Enter.” This creates what's called a "soft break" and is useful for addresses, poems, or any content where line breaks matter but you want to maintain paragraph continuity.

Here is the first paragraph on line 1.

And here is the second paragraph on line 3.

This third paragraph is on line 5.
And this fourth paragraph is on line 6, but will show up on the same line as the the third paragraph without a blank line in between.

Headings

Markdown supports six levels of headings, created by starting a line with one to six hash symbols followed by a space and your heading text. Level 1 headings use a single hash # Heading 1, level 2 uses two hashes ## Heading 2, and so on up to level 6 with six hashes ###### Heading 6.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Alternative syntax. You can also create level 1 and level 2 headings using underline-style syntax by "underlining" your text with equals signs or hyphens on the next line.

Heading level 1
===============
Heading level 2
---------------

Heading IDs. Many Markdown processors automatically generate IDs for headings based on their text, allowing you to create anchor links within your document using [Link text](#heading-id).

### Example heading {#example-id}

Emphasis

Bold text. Create bold text by surrounding it with two asterisks **bold** or two underscores __bold__, with most style guides preferring asterisks for consistency.

Here's an example of some **bolded text**.

Italic text. Make text italic by surrounding it with single asterisks *italic* or single underscores _italic_, though asterisks are more commonly used.

Here's an example of some *italic text*.

Bold and italic. Combine both by using three asterisks ***bold and italic*** or mixing syntax like **_bold and italic_**.

Here's an example of some ***bold and italic text***.

Strikethrough. Cross out text using two tildes on each side ~~strikethrough~~, though this requires extended Markdown support on some platforms.

Here's an example of some ~~strikethrough text~~.

Lists

Unordered lists. Create bullet points by starting lines with hyphens, asterisks, or plus signs followed by a space, and indent nested items with two or four spaces for sub-lists.

Here's an example of an unordered list:
- List item 1
- List item 2
- List item 3

Ordered lists. Number your items with digits followed by periods 1. First item, and Markdown will automatically renumber them in the output even if your source numbers are out of order.

Here's an example of an ordered list:
1. List item 1
2. List item 2
3. List item 3

Task lists. Create interactive checklists using - [ ] Incomplete task for unchecked items and - [x] Complete task for checked items, widely supported in project management tools.

Here's an example of a task list:
- [ ] Task example 1
- [ ] Task example 2
- [x] Completed task example 1
- [x] Completed task example 2

Links

Inline links. The most common link format uses square brackets for the link text followed immediately by parentheses containing the URL: [Knock](https://knock.app).

Here's an example of an [inline link](https://knock.app).

Mailto links. Linking to email addresses works in a similar fashion, but you must use a mailto link: [Contact us](mailto:[email protected]).

Here's an example of an [mailto link](mailto:[email protected]).

Reference links. For documents with many repeated links, use reference-style links by defining the URL once and referencing it multiple times: [Knock][1] with [1]: <https://knock.app> defined elsewhere.

Here's an example of a [reference link][1].

[1]: <https://knock.app>

Adding titles to links. If you want to go a step further, you can add titles to links that appear on hover by including them in quotes after the URL: [Knock](https://knock.app "Notification infrastructure"). Try hovering over the link below to see its title.

Here's an example of a [link with a title](https://knock.app "Nice work, you found the title!").

Images

Basic image syntax. Insert images using an exclamation mark followed by alt text in square brackets and the image URL in parentheses: ![Alt text](https://image-url.jpg).

![This is fine](https://media.npr.org/assets/img/2023/01/14/this-is-fine_custom-b7c50c845a78f5d7716475a92016d52655ba3115.jpg)

Linked images. Make images clickable by wrapping the image syntax in link syntax: [![Alt text](image-url.jpg)](https://knock.app).

[![This is fine](https://media.npr.org/assets/img/2023/01/14/this-is-fine_custom-b7c50c845a78f5d7716475a92016d52655ba3115.jpg)](https://topatoco.com/collections/this-is-fine)

Image titles. Add hover text to images the same way as links: ![Alt text](image-url.jpg "Image title"). Try hovering over the image below to see its title.

![This is fine](https://media.npr.org/assets/img/2023/01/14/this-is-fine_custom-b7c50c845a78f5d7716475a92016d52655ba3115.jpg "Nice work, you found the title!")

Blockquotes

Create blockquotes by starting lines with a greater-than symbol and a space > This is a quote. Multi-line quotes can use a > at the start of each line, or just at the beginning of each paragraph within the quote.

Blockquotes can also be nested by using multiple greater-than symbols >> Nested quote and can contain other Markdown formatting like lists, headings, and emphasis.

Horizontal rules

Insert a horizontal rule to separate sections by typing three or more hyphens ---, asterisks ***, or underscores ___ on a line by themselves. For clarity and compatibility, ensure there's a blank line before and after the horizontal rule, and most style guides recommend using three hyphens for consistency.

Section with some content.

---

Next section separated by a horizontal rule.

---

Another section with another style of separator.

---

Three or more hyphens, asterisks, or underscores all work.

Next up, we’ll show you how to go beyond these basic syntax with some extended Markdown syntax.

Extended Markdown syntax

Extended Markdown syntax varies across different "flavors" or implementations, with each platform adding features based on their users' needs.

For example, GitHub Flavored Markdown (GFM) adds features like task lists and tables, while MultiMarkdown includes footnotes and metadata. CommonMark attempts to standardize core Markdown behavior, though most platforms build upon it with their own extensions.

Before using extended syntax, check your target platform's documentation to ensure compatibility. Features that work in GitHub might not work in Discord, and syntax that renders in Obsidian might not display correctly in a static site generator. When writing for multiple platforms, stick to basic Markdown for maximum compatibility.

Tables

Tables use pipes | and hyphens - to create structured data layouts, with the header row followed by a separator row that defines column alignment. Basic table syntax looks like | Header 1 | Header 2 | on the first line, |----------|----------| on the second line, and | Cell 1 | Cell 2 | for data rows.

You can control column alignment by adding colons to the separator row: |:---| for left alignment, |:---:| for center alignment, and |---:| for right alignment. Most table implementations also support inline Markdown formatting within cells, allowing you to use bold, italic, and links inside your table data, which makes tables more flexible than they might initially appear.

When working with tables, it's best to keep them simple and consider using code blocks for complex data instead. Markdown tables become difficult to maintain when they grow beyond a few columns or contain lengthy content, and the source formatting can become unwieldy when trying to align pipes across many columns or lengthy cell contents.

Code

Inline code. Wrap code snippets within sentences using single backticks: `const name = "Knock"` appears as const name = "Knock".

Use `inline code` for short snippets within text.

Code blocks. Create multi-line code blocks by indenting each line with four spaces or a tab, though this method doesn't support syntax highlighting.

Fenced code blocks. Use three backticks on separate lines to create code blocks with better control: three backticks on the opening and closing lines with your code in between.

Syntax highlighting. Add language identifiers after the opening backticks for syntax highlighting: javascript for JavaScript, python for Python, or bash for shell commands.

Subscript and superscript

Subscript. Create subscript text using tildes: H~2~O renders as H₂O in processors that support this syntax.

H~2~O

Superscript. Create superscript text using carets: X^2^ renders as X² where supported.

X^2^

Footnotes

Footnotes let readers reference additional information without interrupting the main text flow. Create a footnote reference using [^1] in your text, then define it elsewhere with [^1]: Footnote content. Most processors automatically number footnotes and create bidirectional links between references and definitions.

Here is a footnote reference in the main text.[^1]

[^1]: This is the content of the first footnote.

Footnote definitions can contain multiple paragraphs and other Markdown formatting when indented properly. They typically appear at the end of the document regardless of where you define them in your source file, and many implementations add a return link after each footnote.

Escaping characters

When you need to display Markdown syntax characters literally, precede them with a backslash to avoid them being interpreted as Markdown syntax. For example, \*not italic\* will display as *not italic* instead of rendering as not italic.

Common characters that need escaping include asterisks, underscores, brackets, parentheses, hash symbols, plus signs, hyphens, and backticks.

Inside code blocks and inline code, escaping isn't necessary since these environments treat all characters literally. For complex scenarios where multiple special characters appear together, consider using code formatting instead of multiple escape characters for better readability.

Inline HTML support

Markdown allows you to directly include raw HTML for formatting that's not available in standard syntax, making it a powerful escape hatch for complex layouts.

Block-level HTML elements like <div>, <table>, and <p> should be separated from surrounding content by blank lines. Inline HTML elements like <span>, <cite>, and <del> can be used anywhere within your text.

However, there are important limitations to consider. Markdown syntax typically isn't processed inside HTML block elements, so you'll need to use HTML tags for all formatting within these blocks.

Additionally, many Markdown processors sanitize or strip certain HTML tags and attributes for security, like <script> tags, especially in user-generated content contexts where malicious code could be injected.

The best practice is to use HTML sparingly and only when Markdown syntax can't achieve your formatting needs, as it reduces the portability and readability of your source files. When you do need HTML, keep it simple and well-documented so future readers understand why plain Markdown wasn't sufficient for that particular formatting challenge.

Start writing better Markdown today

Markdown transforms the writing experience by removing the friction between thought and formatted text. With just a few simple symbols, you can create professional documentation, engaging blog posts, and well-structured notes that look great everywhere. The syntax you've learned in this guide works across thousands of applications and platforms, making it one of the most valuable tools in your digital toolkit.

The best way to master Markdown is to start using it in your daily tasks. Pick a note-taking app that supports Markdown, write your next README file in Markdown, or contribute to documentation on GitHub. You can use Markdown for your messaging templates with Knock. Sign up for a free account today to get started.

As you write more Markdown, the syntax becomes second nature, and you'll find yourself formatting text faster than ever before while maintaining complete control over your content's structure and presentation.