Code blocks

Code blocks in guides are highlighted at build time with Shiki, through Fumadocs' default MDX pipeline. Everything on this page works in any .mdx file under content/, with no setup. The last sections show how to change the pipeline itself.

This page covers code blocks in guides. Code samples in the API reference are generated: see Code samples.

Add a titleCopy Anchor Link

```ts title="src/main.ts"
await app.listen(3000);
```

The title shows above the block, with an icon for the language.

Group blocks as tabsCopy Anchor Link

Give consecutive code blocks a tab and they become one block with tabs:

```ts tab="TypeScript"
const res = await fetch('/v1/bookings');
```

```python tab="Python"
res = requests.get('/v1/bookings')
```

For tabs that mix code and prose, use the <Tabs> component. See Components.

Package-manager tabsCopy Anchor Link

A block with the language npm becomes tabs for npm, pnpm, yarn and bun, with the command translated for each:

```npm
npm install @orbitdocs/nestjs
```

Line numbers and copy buttonCopy Anchor Link

```ts lineNumbers
const a = 1;
const b = 2;
```

```ts lineNumbers=10
// numbering starts at 10
```

```bash noCopy
echo "no copy button on this block"
```

Highlight, diff and focus linesCopy Anchor Link

Add a comment at the end of a line. The comment is removed from the output. word: goes on its own line and applies to the lines after it.

```ts
const client = createClient(); 
const key = process.env.API_KEY;
const old = 'v1'; 
const next = 'v2'; 
await client.connect(); 
```

Use the comment syntax of the block's language: # [!code highlight] in Python or Bash.

Change the syntax themeCopy Anchor Link

The default themes are github-light and github-dark. Pick others with codeBlocks in the config:

codeBlocks: {
  themes: { light: 'catppuccin-latte', dark: 'catppuccin-mocha' },
  // Language of a fence without one (default `plaintext`).
  defaultLanguage: 'ts',
},

Any Shiki theme name works. codeBlocks applies to guides and to the MDX files in reference/; the API reference highlights its own samples. Restart orbitdocs dev after changing it.

The other Shiki options (langs, langAlias, inline, transformers, …) go in lib/source.ts, as rehypeCodeOptions of orbitMdxOptions(). They are merged over codeBlocks:

import { orbitMdxOptions } from '@orbitdocs/next/mdx-plugins';
import { defineDocs } from 'fumadocs-mdx/macro';

const docs = defineDocs({
  dir: 'content',
  docs: {
    // …keep the schema, postprocess and lastModified options that are already here
    mdxOptions: orbitMdxOptions({
      rehypeCodeOptions: { langAlias: { conf: 'ini' } },
    }),
  },
  meta: { schema: metaSchema },
});

Add MDX pluginsCopy Anchor Link

The default pipeline includes GitHub-flavored Markdown, heading anchors, image sizes, code tabs, package-manager tabs, search structure and Shiki highlighting. Math, diagrams and other syntax need a plugin.

Example: LaTeX math with KaTeX.

npm install remark-math rehype-katex katex

import rehypeKatex from 'rehype-katex';
import remarkMath from 'remark-math';

mdxOptions: orbitMdxOptions({
  remarkPlugins: [remarkMath],
  // rehypeKatex must run before Shiki: put it first.
  rehypePlugins: (plugins) => [rehypeKatex, ...plugins],
}),

@import 'katex/dist/katex.css';

remarkPlugins and rehypePlugins take a list, added to the defaults, or a function that receives the default list and returns the final one.

Code block optionsCopy Anchor Link

Next stepsCopy Anchor Link