Annotations

Annotations are the small authored markers that turn plain MDX into structured website content. They define project subpages, stable slugs, summaries, showcased files, and code presentation details without moving that information into route code.

This page collects the building blocks that are useful when writing by hand and when asking agents to produce content. Each section shows the source pattern first, then explains what the rendered page does with it.

Block Framing & Defaults

Block-level presentation annotations control default chrome, line indicators, headers, and overlay controls without requiring a custom component in the MDX file.

Language Label

Code blocks show their current language as a label by default. It does not switch or change the code. Use !no-language to hide it, or !language to enable it explicitly.

1
export const packageManagers = ['yarn', 'pnpm', 'npm'];

1
// !language
2
export const packageManagers = ['yarn', 'pnpm', 'npm'];

1
// !no-language
2
export const packageManagers = ['yarn', 'pnpm', 'npm'];

Line Numbers

Non-shell code displays line numbers by default. Shell blocks omit them so short commands stay compact, but !line-numbers opts an individual shell example back in. Use !no-line-numbers to opt out of the default on any language.

1
const managers = [
2
  'yarn',
3
  'pnpm',
4
  'npm',
5
];

1
// !line-numbers
2
const managers = [
3
  'yarn',
4
  'pnpm',
5
  'npm',
6
];

// !no-line-numbers
const managers = [
  'yarn',
  'pnpm',
  'npm',
];

1
# !line-numbers
2
# !no-shell-prompt
3
function website_build() {
4
  local project=${1:-website}
5

6
  if [[ $project == website ]]; then
7
    yarn install --immutable
8
    yarn moon run "$project:build"
9
  else
10
    print "Unknown project: $project" >&2
11
    return 1
12
  fi
13
}

Copy Button

Shell blocks show a copy button by default, while non-shell blocks keep copy buttons opt-in. Use !copy to enable copying, or !no-copy to hide it.

1
// !copy
2
export const packageManagers = ['yarn', 'pnpm', 'npm'];

When !copy is present alongside the language label, both share the same overlay rail.

Shell Prefix

The project runs through the repository's Yarn and Moon tasks. Shell blocks show the $ prefix and a copy button by default. Use !no-shell-prompt or !no-copy when a shell block should not show either one, or use !shell-prompt and !copy to add them to another code language.

yarn moon run website:build

# !no-shell-prompt
yarn moon run website:build

# !no-copy
yarn moon run website:build

# !no-copy
# !no-shell-prompt
yarn moon run website:build

File Names

Plain fence metadata is rendered as a file name above the code block.

1
```ts package-manager.ts
2
export const packageManagers = ['yarn', 'pnpm', 'npm'];
3
```

Visual & Line Annotations

Annotations can draw attention to a specific part of an example or adjust line presentation without changing the code readers can copy.

Marked Code

!mark highlights the next line. Add a range or regular expression to mark only part of a line, and add a color after the selector to override the theme accent.

1
function publish(version: string) {
2
  // !mark blue
3
  assertCleanWorkingTree();
4
  // !mark[/version/] gold
5
  return createRelease(version);
6
}

Diffs

!diff + and !diff - identify inserted and removed lines. Diff styling reuses the mark annotation so both features retain the same visual structure.

Use !noop before an annotation marker to show that marker as code instead of interpreting it. The noop prefix is omitted from the rendered line.

1
export function packageCommand(manager: string) {
2
  // !diff -
-
3
  return `${manager} install`;
4
  // !diff +
+
5
  return manager === 'npm' ? 'npm install' : `${manager} add`;
6
}

Folded Details

!fold replaces matching inline content with an expandable ellipsis. The native disclosure keeps the full text in the server-rendered document and remains expandable without JavaScript.

1
// !fold[/className="(.*?)"/gm]
2
export function Status() {
3
  return <span className="...status status--ready">Ready</span>;
4
}

Word Wrapping

!word-wrap keeps long lines inside the available width and aligns wrapped text with the original indentation.

1
// !word-wrap
2
const command = createPackageManagerCommand({ manager: 'yarn', operation: 'exec', package: 'typescript', executable: 'tsc', arguments: ['--watch', '--preserveWatchOutput'] });

Complex Components

Some authoring patterns need more than a single markdown element. These components keep the MDX source readable while letting the rendered page group related examples, controls, or comparisons into one block.

Code Tabs

Related code blocks that describe one change across several files belong together rather than stacked one after another.

1
<CodeWithTabs>
2

3
```ts !!tabs component.tsx
4
export function Example() {
5
  return <p>Example</p>;
6
}
7
```
8

9
```ts !!tabs component.css.ts
10
export const exampleStyle = style({
11
  display: 'block',
12
});
13
```
14

15
</CodeWithTabs>

1
export function Example() {
2
  return <p>Example</p>;
3
}

1
export const exampleStyle = style({
2
  display: 'block',
3
});

Package Manager Commands

The !package annotation describes a package-manager-neutral command and renders the matching Yarn, pnpm, and npm forms as tabs.

Install packages

yarn add typescript zod

pnpm add typescript zod

npm install typescript zod

```sh !package install typescript zod
```

Each variant adds the same two packages to the current project and passes their names through unchanged. Only the command differs: Yarn and pnpm distinguish adding a dependency from installing the project, so they use add, while npm overloads install.

Scaffold a project with a one-off package

yarn dlx create-vite my-app --template react-ts

pnpm dlx create-vite my-app --template react-ts

npx create-vite my-app --template react-ts

```sh !package exec create-vite my-app --template react-ts
```

Here the binary and the package share a name, so no package needs to be declared. The project name and template arguments are identical everywhere, and only the runner changes: yarn dlx, pnpm dlx, and npx.

Run a binary from a named package

yarn dlx -p typescript tsc --watch

pnpm dlx --package typescript tsc --watch

npx --package typescript tsc --watch

```sh !package exec --package typescript tsc --watch
```

When the binary does not match the package that supplies it, the package has to be named explicitly. The runners differ as above, and so does the flag: Yarn spells it -p, while pnpm and npm both use --package.