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

BulkheadOS 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.

Set BULKHEAD_SITE_URL to your workspace URL and BULKHEAD_API_TOKEN to a scoped API token before running the request.

curl -X POST "$BULKHEAD_SITE_URL/api/v1/editor-preview"   -H "Authorization: Bearer $BULKHEAD_API_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\">const published = true</pre>"
}

Shell Example

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

curl -fsS "$BULKHEAD_SITE_URL/api/search.json?q=docs&limit=3"
curl -I "$BULKHEAD_SITE_URL/llms.txt"

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 keeps product truth, public docs, support knowledge, and approved answer paths aligned.",
      "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.