Roam is a note-taking tool with an important principle: frictionless entry of information. The Daily Notes Page is one application of this principle, but so is Markdown. In this article, I'll show you everything you need to know for frictionless entry of formatted text in Roam.
Markdown is a way to style text on the web or note-taking apps, using plain text only. While many editors and word processors have shortcuts to style text (like bold, italics, or strikethrough), copying your text outside of these tools will remove all formatting. That's not the case with Markdown.
In Markdown, the paragraph above looks like this:
[Markdown] (https://www.markdownguide.org/getting-started/#what-is-markdown) is a way to style text on the web or note-taking apps, using plain text only. While many editors and word processors have shortcuts to style text (like **bold**, _italics_, or ~~strikethrough~~), copying your text outside of these tools will remove all formatting. That's not the case with Markdown.
As you see, the formatting is all done via plain text. How the formatting is interpreted depends on the writing tool you're using as not all use the same version of Markdown.
A word on Markdown flavors
It’s important to mention that not all apps use the same version (also called “flavor”) of Markdown. Each app has its own needs and shortcodes, so Markdown formats differ a bit.
For example, the most popular Markdown flavor (Github) uses a single * or _ on each side of a phrase to italicize it. In Roam, you need __ (double underscores) on each side to italicize a phrase.
Because of this, it’s sometimes necessary to clean up the exported files before you can use them in other Markdown apps (although this depends on the app). One popular way to convert large volumes of Roam Markdown to standard Markdown is by using the note-taking app Obsidian (by the creators of Dynalist).
In this article I'll mention where the Roam Markdown flavor differs from the standard (GitHub) flavor.
Text decoration
The most used Markdown syntax is probably to style text. Things like bolding, italicizing, and striking through are easily done with Markdown. But, as with many Markdown flavors, Roam does a few things differently.
To bold a snippet of text, you simply need to add ** on both side. Like this: **bold**. An even quicker way is to hit the Ctrl/Cmd-b keyboard shortcut to have Roam add the asterisks and place the cursor in the middle. This is the same syntax that's used in most Markdown editors.
To italicize text in Roam, you need to add __ (double underscore) to both sides if the text snippet. You can also use the Ctrl/Cmd-i keyboard shortcut to achieve the same. Roam's syntax differs from most Markdown flavors in that it uses double underscores, whereas most other editors use a single underscore on both sides to italicize text.
To strikethrough text in Roam you simply add ~~ on both sides of the text. The shortcut is Ctrl/Cmd-y. In this case, Roam follows most flavors' syntax.
Last but not least, it's also possible to highlight text in Roam using Markdown. This isn't part of most Markdown flavors, but I'm glad Roam did decide to add it. To highlight a snippet of text, add ^^ to both sides. Alternatively, use the Ctrl/Cmd-h shortcut.
Text decoration quirks
While Roam's Markdown flavor is solid overall, it also has a quirk to keep in mind.
While you can italicize part of a bolded text, you can't bold part of an italicized text. That means that you can nest __ within **, but you can't nest ** within __. If you do, it'll look something like this:
__You can't bold part of an italicized text.__
As you see, the bold Markdown gets processed, but not the Markdown for italics. This would be the correct rendering—alas that's not the case in Roam:
You can't bold part of an italicized text.
Headings
To add headings in Roam, you can use the same syntax used in almost any other Markdown flavor by adding one or multiple hashtags at the beginning of a block, followed by a space:
# Heading 1
## Heading 2
### Heading 3
Alternatively, you can use a keyboard shortcut to turn the block your cursor is in into a header. To do this, hit Ctrl-Alt (Cmd-Option on Mac) and the number of the heading level. So, for heading 1 you'd use Ctrl-Alt-1, and for heading 2 you'd use Ctrl-Alt-2.
An important difference between Roam's Markdown flavor and other flavors is that Roam only supports three heading levels (1-3).
Links
For links, Roam uses the same syntax as used in other Markdown flavors. Simply wrap the label of the link between square brackets and the URL between parenthesis. Like this:
[Link label](URL)
This syntax often trips people up as they accidentally swap the square brackets and parenthesis. Luckily, there's a keyboard shortcut: Ctrl/Cmd-k.
When you select a text or URL and hit the link shortcut, Roam will figure out what you've selected and put it between the right brackets. So, if you've selected text it'll place it between square brackets, whereas URLs will automatically be put between parenthesis upon hitting Ctrl/Cmd-k.
Images
In Markdown, images are essentially links. However, to show the image inline you need to add an exclamation mark in front of the square brackets:
As you can see, it's not necessary to fill the label text as this Markdown syntax loads images directly. However, you can add text between the square brackets as alt text (that appears when you hover over the image).
When you upload an image (using the /upload command or by dragging it into a block), Roam will automatically generate the image Markdown for you.
Lists
In Roam, everything is a list, so why bother learning the Markdown for it?
When you use an external text expansion tool, you need to add the bullets in Markdown if you want Roam to properly load in the text.
To create a list using Markdown, simply add a minus sign in front of the text, followed by a space:
- List item
- List item
- List itemLines and blockquotes
To help structure pages and make them more pleasant-looking, Markdown (and Roam) have two useful features: horizontal lines and blockquotes.
To create a horizontal line in Roam, simply type three minus signs (---) and click outside the block to render it. It'll look like this:
Another nice feature of Markdown is the ability to turn a paragraph into a blockquote, enabling you to style it differently from other text. Blockquotes are often used for quotes or text that's not your own.
To create a blockquote in Roam, simply place the greater-than sign at the beginning of a block, followed by a space:
> Text that's turned into a blockquote.
Depending on the styling of the Markdown tool you use, it'll render something like this:
Text that's turned into a blockquote.
One handy workflow that's possible with the blockquote feature in Roam is that you can wrap the greater-than sign with double square brackets ([[>]]). While it doesn't change the formatting of the blockquote, it will enable you to filter on the > value (as placing it between brackets turns it into an internal link you can filter on). Personally I use this in my Readwise metadata so that all highlights are tagged as a blockquote, indicating the text aren't my own words.
Code (blocks)
If you want to document code, Roam is a great tool to use thanks to its inclusion of the code syntax of Markdown. This will show the text marked in a monospace font.
To turn a snippet of text into code format, simply wrap it between single backticks (`):
`Text to show in monospace font`
Single backticks are useful if you want to change only part of a block to code format. But if you want to turn an entire block into a code block (including syntax highlighting), use three backticks (```).
In Roam, triple back ticks automatically convert to six, which automatically turns into a code block with javascript as language. You can change the language, both via the dropdown and the shortcode. The selected language changes the syntax highlighting:
```javascript
```Rendered, the code block looks like this in Roam:
Simply place your cursor within the code block and type away.
Other resources
If you want to dive deeper into Markdown and its de facto standard syntax, I recommend you check out the following free resources.
While Roam's Markdown is useful for working within the tool, you'll need to learn the Markdown standard if you want to use it in other tools. After going these resources, Markdown will have no more secrets for you.
- GitHub Guide: Mastering Markdown
- Deep dive: Markdown Guide
- Mini course: Mastering Markdown by Wes Bos
Join the conversation.