To add a code block in Notion, type /code on an empty line and press enter, or hover over the line, click the + on its left and choose Code. Click the language name at the top left of the block to search for your language, then type or paste the code. The block colors the syntax and adds Copy, Wrap code and Caption buttons, but it doesn't execute programming code; Notion's help lists no native line-number option. I'd make /code your default, because it keeps your hands on the keyboard.
For a single command, file path or property name inside a sentence, choose inline code instead. For anything longer than one line, or anything a reader will copy, choose a code block. For a flowchart or a pie chart, choose a code block set to Mermaid. For a working calculator or form, a code block is the wrong tool, and the last section shows where that belongs.
How do you add a code block in Notion?
Notion documents three ways to create one. They all give you the same kind of block, so pick by where your hands are.
- Slash command: type
/codeand press enter. Notion's help page on code blocks and its keyboard shortcuts page both list it. - Block menu: hover over a new line, click the + that appears on the left, choose Code and press enter.
- Keyboard shortcut: press cmd + option + 8 on a Mac or ctrl + shift + 8 on Windows and Linux. Notion's keyboard shortcuts page writes it as cmd/ctrl + option/shift + 8.
Click inside the new block to type or paste your code. The shortcut has two catches that Notion points out itself: Windows machines might already have ctrl + shift bound to another function, and its shortcut instructions are written for English/QWERTY keyboards. If the 8 shortcut does nothing on your machine, /code still works.
On a phone or tablet, the routes change. Notion's guide to writing and editing says the mobile app has no / commands and no icons that appear on hover; content comes from the editing toolbar above your keyboard, where the + opens the full menu of block types.
Some third-party guides give different keys, so check before you memorize one. Bullet's guide to writing code in Notion lists cmd + option + shift + 8 for Mac, an extra shift that Notion's own shortcut page doesn't include. ONES' article on the code block shortcut says that typing three backticks followed by a language name and pressing enter creates a block. That combination isn't on Notion's shortcut page. I'd use the documented /code route instead of teaching a shortcut the official list doesn't confirm. For the rest of the keys, our check of which popular Notion shortcut lists hold up covers the full table.
How do you pick or search the language?
- Click the name of the language at the top left of the code block.
- Type the name of your programming language to search.
- Press enter to select it.
The language decides the syntax coloring, and Notion's guide to code blocks puts its highlighting at over 60 programming languages. Set the language every time you create a block rather than trusting whatever a new block shows; coloring only helps when it matches the code. Not everything you paste is a programming language, either. Notion's block reference lists plain text among the values a code block accepts, alongside Markdown, LaTeX, JSON, YAML and shell, so an error message or a log excerpt can still sit in its own copyable block.
How do you wrap, copy or caption code?
Hover over the code block and three buttons appear at its top right: Copy, Wrap code and Caption. The ••• menu next to them holds more options; it is hidden for readers with Can view access.
- Wrap code folds long lines onto several lines, so nobody has to scroll sideways. Click it again to turn wrapping off. You can also switch it on from a menu: click ••• at the top right or ⋮⋮ on the left, or right-click the block, then switch on Wrap code.
- Copy puts the code on your clipboard, ready to paste into an editor, a terminal or a message.
- Caption adds a short note to the block, for whatever you want to say about the code.
I'd switch on Wrap code for anything a client or a teammate reads on a laptop screen, and leave it off for a config file whose line structure is the point. Use the caption for the two things readers ask most: what the code is for and where it runs. “Run from the project folder after pulling the latest changes” saves a message later; “Code” saves nothing.

Should you use inline code or a code block?
Use inline code for a short piece of code inside a sentence, such as a file name, a command or a property name. Use a code block for anything with more than one line, anything that needs syntax coloring, or anything someone will paste somewhere else.
Notion's shortcuts page gives two ways to make inline code. Type a backtick (`) on both sides of your text, the key to the left of 1 on an English keyboard, or select the text and press cmd/ctrl + E.
My rule is simple: if a reader needs to copy it, it goes in a block, because the block comes with a Copy button and a caption for context. If a reader only needs to recognize it in a sentence, like npm install or a property called Status, inline code is enough and keeps the paragraph readable.
How do you draw a diagram with Mermaid?
Set a code block's language to Mermaid and Notion can draw the diagram that the code describes. Notion's release note introducing Mermaid diagrams names flowcharts, pie charts and user journey diagrams among the options and says the syntax is easy to learn even if you don't usually write code.
- Create a code block and click the language name at the top left.
- Search for Mermaid and press enter.
- Write or paste the diagram code.
- Use the second dropdown at the top left to show a live Preview of the chart, or choose Split to see the code and the chart together.
A small approval loop for client work looks like this in Mermaid syntax:
graph LR
A[Client brief] --> B[Draft]
B --> C{Approved?}
C -->|Yes| D[Deliver]
C -->|No| B
I'd write in Split, so each edit shows up in the chart as you type, and switch to Preview before you share the page, so readers get the chart rather than the syntax behind it. If a diagram comes in from another Markdown tool, check the block before you share it. Markdowntools' guide to Markdown in Notion found that a fenced block tagged mermaid imports as a plain code block holding the diagram source. The release note says you can select Mermaid in the language dropdown of any code block, so set the language to Mermaid if it isn't already, then pick Preview.

Can a code block show line numbers?
Notion's native code-block controls cover language, wrapping, copying and captions, with no documented line-number option. The Notion Boost feature list includes a “Show code line numbers” setting; ILoveFreeSoftware's walkthrough describes that extension workaround. Those numbers belong to the browser extension. Other readers won't see them unless they run it too, so they aren't reliable references on a page you share with a client or a team. I wouldn't install an extension just for this.
These work for every reader instead:
- Point to lines in the caption: “The second line sets the output folder; change it before you run this.”
- Split long code into short blocks: give each block its own caption, so you can say “the second block” instead of “line 14.”
- Review line by line where the code lives: if a review needs exact line references, run it in the tool that holds the code and put a link or an embed on the Notion page. Notion's writing guide lists a GitHub Gist embed for code, notes and snippets and a CodePen embed for code snippets.
Can you put code in a database property?
Not as a code block. A code block is a block, and blocks live in a page body, including the page that opens when you click a database row. A database cell is a property, and a Text property stores rich text rather than blocks, which is the same split that decides why bullet points behave differently in a database cell.
The structure I'd use for a snippet library is one database where each row is a snippet:
- the row's name says what the snippet does, like “Rename exported files”;
- a Select property holds the language, so you can filter a view to Python or SQL;
- a Text property holds a one-line note, such as where the code runs;
- the code itself goes in a code block inside the row's page, with Copy and Caption available.
Start with the handful of snippets you paste every week. Add a property only when you catch yourself searching for a snippet and can't find it with the ones you have.
What survives when you paste, import or export code?
For code blocks, the useful evidence is documented behavior: what each route into Notion produces, according to Notion's help and one hands-on Markdown guide. The three creation routes all start a plain code block; the two Markdown routes are where code can change shape.
| Route | How | What you get | What the sources say | Best for |
|---|---|---|---|---|
| + menu | Hover over a new line, click +, choose Code, press enter | An empty code block | Notion's code block help page | Mouse users and first-timers |
/code | Type /code, press enter | An empty code block | Code block help page and keyboard shortcuts page | Everyday use on desktop and web |
| Shortcut | cmd + option + 8 (Mac); ctrl + shift + 8 (Windows, Linux) | A code block | Shortcuts page; written for English/QWERTY keyboards, and Windows may already bind ctrl + shift | Frequent use on a QWERTY keyboard |
| Paste Markdown | Paste text that contains a fenced code block | Notion converts it as you paste | Markdowntools: tables and code blocks often break, because paste is processed in real time | One short snippet you check right away |
| Import a .md file | Settings → Import → Text & Markdown, or ••• → More → Import on the target page | A page with code blocks | Notion: imports headings, lists and code blocks; anchor links and nonstandard Markdown extensions may not import cleanly. Markdowntools: fenced blocks with language labels become highlighted code blocks; the most reliable route | A whole document with several snippets |
For one short snippet, paste it and look at the result before you move on. For a document with several code samples, I'd import the file. Notion's import help lists code blocks among what its Text & Markdown importer brings across, and markdowntools rates file import above paste for fenced code. Import runs on desktop and web, not on mobile, and Notion caps Markdown imports at about 120 files every 12 hours, which only matters if you're moving a whole snippet library at once.
Other file types are less tidy. Notion's import help says code block style doesn't import correctly from Google Docs, and that code may not appear as originally formatted after a PDF import. Its HTML importer, on the other hand, lists code blocks among what it brings in. After a Google Docs or PDF import, I'd scan for code and rebuild those blocks with /code rather than fix the formatting line by line.
Going the other way, any non-database page can be exported as Markdown. Click ••• at the top right of the page, open More, choose Export, then pick Markdown & CSV from the format dropdown; Notion's export help says the files open as plain text with Markdown syntax. Before a handover, inspect links to other Notion pages in the Markdown. A link that still points to Notion opens the live page with its access requirements, not a local copy of that page. For a client handover where the export has to stand on its own, our guide to backing up a Notion client project covers export scope and what to check in the archive.
How do you add a code block through the API?
In the API, a code block is a block of type code with three parts: rich_text for the code itself, caption and language. Notion's block reference gives this example:
{
"type": "code",
"code": {
"caption": [],
"rich_text": [{
"type": "text",
"text": { "content": "const a = 3" }
}],
"language": "javascript"
}
}
The language has to be one of the values the reference lists, such as python, bash, json, mermaid or plain text. Long code runs into the API's request limits: each rich text object's text content tops out at 2,000 characters, and an array of rich text objects holds up to 100 elements. Anything longer than 2,000 characters has to go in as several text objects in the same rich_text array. The whole request must also fit within the 500KB payload limit. Our guide to creating a Notion page through the API covers the request around it, including where those limits bite.
What can't a code block do?
A code block displays programming source; it doesn't execute it. Mermaid renders diagram syntax, but a Python or JavaScript code block won't run your program. Notion's help presents code blocks as a way to display source apart from the rest of the page. That leaves three cases where you need something else.
- Something interactive, like a calculator or a quiz: that's the HTML block, which our guide to Notion embeds and HTML blocks covers.
- Live code kept somewhere else: embed it with the GitHub Gist or CodePen embed, so the page points at the code where it's maintained instead of holding a pasted copy.
- A long optional snippet that buries the rest of the page: put the code block inside a toggle, and our toggle guide shows how to fill one.
One more boundary is about access, not features. A code block shows whatever you paste to everyone who can open the page, so keep API keys, passwords and tokens out of any snippet on a page a client or a guest can see. The block handles display, coloring and copying; you still decide which version of the code people should copy and who gets to see it.
Questions that come up next
Can you turn existing text into a code block?
Yes. Click the ⋮⋮ handle next to the block, choose Turn into, which Notion describes as transforming a block into another type of block, and pick the block type from the list. Typing /turn at the start or end of a block brings up a similar list of choices. Each line you ended with enter is its own block, so for several lines of code it's usually quicker to create one block with /code and paste them all in.
Should math go in a code block or an equation?
Use an equation if readers should see the math itself: /math or /latex adds a block equation written in TeX, and /equation adds one in line with your text. Set a code block to LaTeX only when readers need the TeX source, for example to copy it into a paper.
Can a code block hold more than one language?
Each code block has one language setting, and the API stores it as a single language value. For an HTML snippet and its CSS, use two blocks, each set to its own language and captioned so readers know which file each one belongs to.