Formatting Documents in Notion

This page is part of 🧰The Toolbox by Danny Smith.

This builds on the general advice in 📝Writing Good Evergreen Documents with some specific tips for formatting documents in Notion.

Headings & Frontmatter

Using Headers well helps readers to understand the structure of your document. Frontmatter is the stuff at the beginning of your document that helps readers understand it's purpose and how to use it.

Headings

Use H2 as your default top-level heading. Only use H1 when you need more than two levels in your hierarchy.
Use a divider to underline every heading.
Default to

Pink for top-level (usually H2)
Purple for second level (usually H3)

Avoid bold text as a psuedo-heading.
Use sentence case in your headings.
Always put emoji at the end of a heading, preceded by a space (unless it's a number emoji - see video).

Frontmatter

Use callouts and TOCs to add useful front matter to your documents.
Set an emoji and header image for long-lived documents.

Heading and Front matter conventions

Emojis

Emojis are super-powerful tools for communication. Use them a lot, but always with intention...

➡️ Don't litter your document 🎉 with 👏 random 🎯 emoji 🔥🎆. It makes reading hard.

In general, if an emoji doesn't convey some meaning or help with reader comprehension, it probably shouldn't be there. Examples of good Emoji-fu...

Emoji in headings help with reader comprehension because they act as visual anchors. Chosen well they also give a visual indication of what the section is about. They make documents easier to scan.
Emoji can convey emotion without the need to write lots of words.

Eg. "Please take the time to do this now 🙏"

Emoji can act as visual cues in the text, but you need to have some convention which you explain to the reader.

Eg. "Stop and make a note whenever you see this (🛑) in the text"

Linking

Use links liberally in notion - one of its greatest powers is the ability to link documents together.

Prefer mentioning notion pages, rather than "Link To".
If you refer to another notion page your text, make it a mention.
Use notion's Bookmark feature to insert better-looking block links.

Linking well in Notion

Lists

Lists are easy to write but hard to parse. Does your list help the reader or are you just using a list because it's easier for you to get your thoughts out. Not everything should be a list.

Use bulleted lists and numbered lists appropriately.
Use toggle lists to hide secondary information where suitable.
Use formatting and colour to differentiate "mini headings" for list items wherever it makes sense.

Tips for lists

Colour and Formatting

Appropriate use of formatting can make a document so much easier to read quickly. But too much formatting makes it harder. It's a good idea to stick to some conventions when using formatting in a document.

Prefer bold to italic.
Only use italic in places where a book would use it.
Avoid multiple text treatments on the same text. There's no point in making something BOLD, ITALIC, AND CAPITALISED. Pick one.
Use code formatting where it helps with reader comprehension. Referring to slack channels like #core-general is a good example.
Be aware that in Notion, colouring blocks and inline text are different things (see loom).

Good Formatting tips

Whitespace

Using whitespace well is one of the easiest ways to make your document more readable.

Add a line of whitespace before and after all embeds, callouts, bookmarks etc.
Add a line of whitespace before and after all long lists.
Add a line of whitespace before headings if the document is feeling crowded.

The power of whitespace

Callouts

Use callouts to bring attention to certain parts of your document. We don't have any hard conventions around colours and emoji for these, but here's a few that you'll see often...

💡

Information - lightbulb and grey background

🎯

Goal - target and blue background

⚠️

Warning or Danger - warning sign and yellow background

🚧

Under construction - Roadworks and grey outline

The important thing is to stick to some sort of convention within your document (or set of documents).

Tables & Databases

Avoid using databases where a simple table will do. Databases come with a lot more features, but if you’re just trying to display some information in a table you can use a simple table like this:

Information	Stuff
Here is some data	1
Here is some more data	5

Code Snippets

If you are writing code, use either the inline code formatting, or code block formatting with the correct language set…

console.log("Hello World");

Embeds

Notion supports a huge number of embeds. Aside from the usual images, tweets, youtube videos, loom videos etc, it’s also possible to embed from internal tools like Slack, Asana, Figma, FigJam, GitHub etc – providing we have an authenticated integration set up. Here’s a Slack message embedded as a preview…

Here’s the same message embedded as a mention:

Make use of this to add context to your documents…

If you're linking something, consider embedding it instead.
If you embed a screenshot, try to use a high-res one (increase the size of the thing you're screenshooting before you snap it)
Use captions to make it obvious what you're embedding and why.

Page Settings

Leave the page settings alone.

Don't set the page to small text.
Don't set the page to full width unless you have a top-level multi-column layout of some sort.
Always add a page emoji.
Always add a cover image for long or important documents.
Lock your page when you share it with everyone. People can still unlock it and make edits, but this prevents "accidental edits".

Messing with the page settings.