On this page:
  • How can you create content in Notion using Markdown?
  • Why learn Markdown?
  • Types of Markdown elements Notion supports
  • Notion Markdown reference and shortcuts
  • Use Swimm to keep Markdown docs up to date

How can you create content in Notion using Markdown?

Notion is a software platform that lets you create notes, outlines, and various online documents. It includes support for Markdown, a markup language for creating and editing plain text documents with various styles and formatting. Notion has a built-in markdown preview that shows Markdown text formatting in real time.

Markdown eliminates the need to write HTML code to style and format text. You can format text in Markdown simply by surrounding parts of your text with a specific syntax. Applications employ markdown to allow users to write to-do lists and notes, and write posts on blogs and websites.

Why learn Markdown?

Here are the main advantages of Markdown:

  • Easy and intuitive—Markdown is accessible to users of all skill levels and uses simple, familiar syntax conventions.
  • Smooth and intuitive workflows—standard writing user interfaces (UI) like Microsoft Word and Google Docs require you to stop writing to select formatting options via buttons and menus. However, when using Markdown, formatting is already included inline with the text.
  • Human-readable in its raw state—unlike raw HTML, which typically includes many tags, Markdown is human-readable. As a result, the syntax is intuitive and flows naturally with the text.
  • Portable files—Markdown is platform-independent, allowing you to create markdown files in various text editors. You can open Markdown files in any Markdown -compatible editor, allowing you to change applications as needed.
  • A reusable skill—Markdown is highly versatile. Once you learn it, you can use it for many activities, such as taking notes, creating content for websites, and producing print-ready documents.
  • Docs-as-Code – For software developers and technical writers, it’s valuable to keep documents as part of a codebase. This enables keeping the documents close to the code that they describe.

Types of Markdown elements Notion supports

Notion supports the following Markdown elements:

  • Headings
  • Paragraphs
  • Line Breaks
  • Bold
  • Italic
  • Ordered Lists
  • Unordered Lists
  • Code
  • Horizontal Rules
  • Fenced Code Blocks
  • Task Lists
  • Emoji (copy and paste)
  • Emoji (shortcodes)
  • Automatic URL Linking

Notion provides partial support for the following Markdown elements:

  • Blockquotes—does not support nested blockquotes.
  • Links—the Notion editor does not allow typing Markdown-formatted links, but you can copy and paste them into Notion. You can use the /link command instead for internal links to pages in Notion.
  • Images—Notion’s editor does not let you format images, but allows you to you to copy and paste Markdown-formatted images. You can use the /images command.
  • Tables—you can copy and paste Markdown-formatted tables, but you can’t type them in Notion’s editor. You can use the /table-inline command.
  • Syntax Highlighting—requires picking a programming language to highlight with the GUI.
  • Strikethrough—requires using only one tilde symbol before and after your text. It does not work when you copy and paste Markdown-formatted text into the Notion editor.

Notion does not support the following Markdown elements:

  • Footnotes
  • Heading IDs
  • Definition Lists
  • Highlight
  • Subscript
  • Superscript
  • Disabling Automatic URL Linking
  • HTML

Related content: Read our guide to notion alternatives (coming soon).

Notion Markdown reference and shortcuts

The lists below includes Markdown syntax available in Notion for common formatting and blocks.

Here are Markdown shortcuts for headings:

  • Heading 1: # + space
  • Heading 2:  ## + space
  • Heading 3: ### + space

Here are Markdown shortcuts for common formatting sytles:

  • Italic: *text* or _text_
  • Bold: **text** or __text__
  • Strikethrough: ~text~
  • Pre-formatted text:`text`

Here are Markdown shortcuts for lists and quotes:

  • Unordered list: *, +, or – (+ space)
  • Ordered list: 1. + space
  • To-do: []
  • Blockquote: ” + space

Here are Markdown shortcuts for toggle and code:

  • Toggle block: > + space
  • Toggle Heading 1: > + space, then # + space
  • Toggle Heading 2: > + space, then ## + space
  • Toggle Heading 3: > + space, then ### + space
  • Code block: “`

The Notion editor also supports the classic text formatting shortcuts that work in programs like Microsoft Word, Google Docs, and Evernote, including:

  • Bold: ctrl/cmd + b
  • Italic: ctrl/cmd + i
  • Underline: ctrl/cmd + u
  • Inline code: ctrl/cmd + e

Use Swimm to keep Markdown docs up to date

Software teams often use Markdown files (.md) to document various aspects of their project. This practice is often called Docs-as-Code.

However, keeping documents in the codebase does not mean it’s easy to keep them up to date. Documents saved within the code are often either very high level or outdated,

Swimm is a documentation platform that helps devs create Markdown docs and then keep them up to date automatically as part of their CI Process. Swimm automatically finds and fixes documents that become outdated because of changes to the code they refer to.
Swimm also has plugins for various IDEs to highlight relevant docs next to the code they relate to. Learn more about how documentation and code are created and maintained together with Swimm.

SIgn up for a 1:1 demo to see Swimm for yourself.