Good docs do not talk about code examples in the abstract. They show real commands, realistic payloads, and enough context that a reader can copy, modify, and move on.

What Good Code Examples Look Like

Bulkhead OS supports plain code blocks for published content and Shiki-backed preview rendering for the editing workflow. The pattern is simple: keep a short explanation above the snippet, label the language clearly, and make the example copyable.

Shiki Preview Example

The editor preview endpoint accepts Markdown and a preferred theme. The response returns rendered HTML ready for a live preview pane.

curl -X POST https://docs.bulkheados.com/api/v1/editor-preview   -H "Authorization: Bearer ENGINE_ADMIN_TOKEN"   -H "Content-Type: application/json"   -d '{
    "markdown": "# Shipping docs faster\n\n~~~ts\nconst published = true\n~~~",
    "theme": "dark"
  }'

{
  "html": "<h1 id=\"shipping-docs-faster\">Shipping docs faster</h1>\n<pre class=\"shiki github-dark\">...</pre>"
}

Shell Example

Shell examples should be safe to paste as-is. Show flags, URLs, and expected output in separate blocks when needed.

pnpm --filter @pobal-os/engine validate:routes
pnpm --filter @pobal-os/engine build
npx wrangler deploy

HTTP Example

For APIs, pair the request with the response. That makes the docs useful even before a reader opens their own tooling.

GET /api/v1/search?q=bulkhead&limit=3&type=inform&visibility=external
Accept: application/json

{
  "results": [
    {
      "title": "Introduction",
      "url": "/introduction",
      "excerpt": "BulkheadOS is a company operating graph for complex software companies...",
      "score": 0.82,
      "node_type": "inform",
      "domain": "Bulkhead Documentation"
    }
  ],
  "meta": {
    "query": "bulkhead",
    "count": 1,
    "limit": 3
  }
}

Markdown Example

When documenting authoring, include the exact Markdown a content editor would type.

## Ship the smallest helpful example

Use a real request, a realistic response, and one short note that explains why the example matters.

> If you can describe an endpoint, you can show it.