Code Blocks

Fenced code blocks are highlighted at compile time with two bundled monochrome themes, pzza-light and pzza-dark. Each block renders as a single bordered surface with a header bar (filename or language, a language icon, and a copy button) and a scrollable body. Switching the site theme never re-highlights the code: both colours are emitted as CSS variables and the stylesheet picks one.

Basic block#

export function add(a: number, b: number): number {
  return a + b;
}

```ts
export function add(a: number, b: number): number {
  return a + b;
}
```

The language after the opening fence selects the grammar and the header icon. Grammars are loaded on demand, so any language shiki supports works, including ts, tsx, js, json, bash, css, html, md, mdx, yaml, toml, rust, go, python, and text for plain output.

Meta attributes#

Everything after the language is the meta string. Attributes are space separated and take the form key, key=value, or key="value with spaces".

Title#

export function add(a: number, b: number): number {
  return a + b;
}

```ts title="lib/math.ts"
export function add(a: number, b: number): number {
  return a + b;
}
```

Line numbers#

import { redirect } from "next/navigation";

export default function HomePage() {
  redirect("/docs");
}

```tsx title="app/page.tsx" lineNumbers
```

Starting at a given line, useful when showing an excerpt:

export const source = createSource(config, {
  components: { Chart },
});

```ts title="lib/source.ts" lineNumbers=12
```

No copy button#

This block cannot be copied from the header.

```text noCopy
This block cannot be copied from the header.
```

Tabs#

Adjacent fences with a tab attribute merge into one block with a tab list in the header. Labels come from the tab value, or from the title or language when the bare tab flag is used.

const greeting: string = "hello";

const greeting = "hello";

```ts tab="TypeScript"
const greeting: string = "hello";
```

```js tab="JavaScript"
const greeting = "hello";
```

Add tab-group to remember the reader's choice and keep every group on the site in sync. The install blocks on this site use the group package-manager, so pick pnpm once and every install fence follows.

brew install node

winget install OpenJS.NodeJS

```bash tab="macOS" tab-group="os"
brew install node
```

```powershell tab="Windows" tab-group="os"
winget install OpenJS.NodeJS
```

Package install#

A fence with the language package-install (or npm) expands into npm, pnpm, yarn, and bun tabs. Write the npm form; the other package managers are derived, including -D dev flags, -g global installs, npx (pnpm dlx, yarn dlx, bunx), and npm create.

npm install -D pzzadocs
npx create-next-app@latest

pnpm add -D pzzadocs
pnpm dlx create-next-app@latest

yarn add -D pzzadocs
yarn dlx create-next-app@latest

bun add -D pzzadocs
bunx create-next-app@latest

```package-install
npm install -D pzzadocs
npx create-next-app@latest
```

The expanded tabs share the package-manager tab group, so they stay in sync with every other install block.

Notation transformers#

Comments in the code itself mark lines and words. The comment is removed from the output and the marked line gets a class the stylesheet styles. The syntax matches the shiki notation transformers.

Highlight#

export function add(a: number, b: number): number {
  return a + b;
}

```ts
export function add(a: number, b: number): number {
  return a + b;
}
```

Diff#

Added lines get a + gutter glyph and a raised surface; removed lines get a - glyph and faint text.

const removed = 1;
const added = 2;
const kept = 3;

```ts
const removed = 1;
const added = 2;
const kept = 3;
```

Focus#

Lines marked focus stay sharp while the rest of the block is dimmed until the reader hovers it.

import { createSource } from "pzzadocs";
import config from "@/docs.config";

export const source = createSource(config);

```ts
export const source = createSource(config);
```

Word highlight#

[!code word:term] outlines every occurrence of term on the following lines.

import config from "@/docs.config";
export const source = createSource(config);

```ts
import config from "@/docs.config";
export const source = createSource(config);
```

Notation comments use the comment syntax of the language, so in CSS write /* [!code highlight] */ and in HTML <!-- [!code highlight] -->.

Inline code#

Wrap text in single backticks for inline code: createSource, --pd-radius, pnpm add pzzadocs. Inline code uses --pd-surface-2 with a --pd-border outline, a 3px radius, and the mono font at 13px.

Themes#

Highlighting uses two themes defined inside the package, pzza-light and pzza-dark. Both are grayscale: keywords are bold, comments are italic, strings and numbers sit a step lighter than plain text, and punctuation is muted. Each token carries both colours as --shiki-light and --shiki-dark (plus font style and weight variables); the stylesheet applies the dark set under .dark. See Theming for how to adjust them.

Using the components directly#

CodeBlock, Pre, CodeTabs, and LangIcon are exported from pzzadocs/mdx for use outside MDX. Content passed this way is not highlighted; highlighting only runs for fenced blocks compiled from MDX.

import { CodeBlock, Pre } from "pzzadocs/mdx";

export function Example() {
  return (
    <CodeBlock title="example.sh" lang="bash" code={'echo "hello"'}>
      <Pre>
        <code>echo "hello"</code>
      </Pre>
    </CodeBlock>
  );
}