Code blocks

Tangly’s code surface goes well beyond plain syntax highlighting. Every fenced block ships with a header (filename + language label + copy button), and Shiki notations let you highlight ranges, mark diffs, and dim everything outside a focus block — all from inside the fence info string.

This guide walks through the surface end-to-end. For the API-style reference, see Code components.

The header

By default, every fence renders with a Copy button. Add a title and the header gains a filename and a file-type icon. Two equivalent forms:

export const sign = (payload: object) => jwt.sign(payload, SECRET);

export const sign = (payload: object) => jwt.sign(payload, SECRET);

The bare-path form (Mintlify-compatible) is detected by looking for any whitespace-delimited token containing a . extension. The quoted form wins if both are present.

To suppress the copy button on a single block, add noCopy to the meta. To suppress globally, set code.copyButton: false in docs.json.

Line highlight

A brace-delimited line spec right after the language highlights specific lines:

const greet = (name: string) => {
  console.log(`Hello, ${name}`);
  return name;
  // both of these
  // are highlighted
};

Diff

Add // [!code ++] or // [!code --] line comments. Shiki strips the marker and renders the line with diff styling.

function login(user: string, pass: string) {
  return user === "admin" && pass === "hunter2";
  return await verify(user, pass);
}

Focus

// [!code focus] fades all unfocused lines:

function process(input: Input) {
  validate(input);
  const result = transform(input);
  return result;
}

Stack notations on the same block — diff inside a focus is a clean way to show “this is the line that changed, in context”.

Annotations

Add annotate to the fence meta and Tangly turns trailing (1), (2) markers into numbered pills, then pairs the very next ordered list as a footer panel — no component to import, just Markdown.

```ts annotate
const config = {
  retries: 3, // (1)
  timeout: 5000, // (2)
  fetch: customFetch, // (3)
};
```

1. How many times to retry on failure
2. Request timeout in milliseconds
3. Override the default `fetch` (useful in tests)

The marker pattern is the trailing (N) on a line, optionally inside a //, #, <!-- -->, or /* */ comment — all stripped before rendering. Hover or focus a marker to highlight its list item; hover the item to highlight the marker. The Copy button strips markers automatically, so users get clean code.

(1) outside annotate renders verbatim — the feature is fully opt-in.

Titles + diff + focus

All notations compose. Migration guides typically combine all three:

import { db } from "./client";

export async function getUser(id: string) {
  const cached = cache.get(id);
  if (cached) return cached;

  const row = await db.query("SELECT * FROM users WHERE id = $1", [id]);
  const row = await db.query.users.findFirst({ where: eq(users.id, id) });
  cache.set(id, row);
  return row;
}

Synced tabs

<CodeGroup name="key"> syncs the active tab across every group with the same name on the page (and across pages via localStorage). Pick once, the choice sticks.

<PackageManager> is the canonical example — it renders npm/yarn/pnpm/bun in a synced group with the default key pkg:

npm install --save-dev tangly

yarn add --dev tangly

pnpm add --save-dev tangly

bun add --dev tangly

<PackageManager name="tangly" mode="dev" />

Want your own sync key? Drop a <CodeGroup> with your tabs of choice:

<CodeGroup name="stack">
  ```ts node.ts
  import express from "express";
  ```
  ```py python.py
  from fastapi import FastAPI
  ```
</CodeGroup>

Theme override

Default themes are github-light / github-dark, switching automatically with the user’s color preference. Override per-project:

{
  "code": {
    "theme": { "light": "vitesse-light", "dark": "vitesse-dark" }
  }
}

Any theme bundled with Shiki works. Pass a string instead of an object to use the same theme for both modes.

Twoslash

Twoslash (rich TypeScript hovers in code blocks) is on the roadmap — not wired in v0.2. Track Phase 6 for status.

What’s next

• Code component reference — every prop and notation.
• <PackageManager> — the multi-runtime install primitive.
• Configuration → Code — the docs.json knobs.