Code blocks

Code blocks should show what readers need to copy or understand. In public template docs, prefer content examples over internal implementation examples.

Good examples#

Use these examples to show code that readers can adapt directly.

---
title: Installation
description: Set up the product workspace.
---

Follow these steps to prepare the project.

## Run checks

Use the lint command before publishing.

Metadata example#

Use tabbed examples when a page needs to compare related files. It keeps the article compact while still showing enough code to copy.

File tabs#

Use file tabs when a guide needs to show related files side by side.

import { StatusBadge } from "./file2";

export function PageHeader() {
  return (
    <header className="space-y-3">
      <StatusBadge tone="ready">Published</StatusBadge>
      <div>
        <h1 className="text-3xl font-semibold">Documentation</h1>
        <p className="text-muted-fg">Write clear product guidance.</p>
      </div>
    </header>
  );
}

When to use file tabs#

Use tabs for related files that should be understood together. Do not hide unrelated examples behind tabs just to save vertical space.

Avoid leaking internals#

Do not make public docs depend on private implementation files unless the user is expected to edit those files directly.

Keep examples portable#

Prefer examples that apply to any buyer using the template: MDX frontmatter, folder structure, metadata files, content checklists, and theme tokens.