---
title: "Code Blocks & Shiki"
description: "Examples for highlighted code blocks, copyable snippets, and Markdown preview rendering."
canonical_url: "https://docs.bulkheados.com/content/code-blocks/"
template: "page-node"
schema_type: "WebPage"
---

<div class="docs-content">
<p class="docs-lead">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.</p>

<h2 id="what-good-code-examples-look-like">What Good Code Examples Look Like</h2>
<p>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.</p>

<div class="docs-example-grid">
  <a class="docs-example-card" href="/ai/search">
    <span class="docs-example-card__eyebrow">API Example</span>
    <strong class="docs-example-card__title">Search requests with real filters</strong>
    <span class="docs-example-card__body">Show the exact query parameters a reader can test against the live site.</span>
  </a>
  <a class="docs-example-card" href="/docs/components">
    <span class="docs-example-card__eyebrow">Component Gallery</span>
    <strong class="docs-example-card__title">Tabs, code groups, accordions, and cards</strong>
    <span class="docs-example-card__body">Use the component reference when you want richer docs layouts beyond plain HTML.</span>
  </a>
</div>

<h2 id="shiki-preview-example">Shiki Preview Example</h2>
<p>The editor preview endpoint accepts Markdown and a preferred theme. The response returns rendered HTML ready for a live preview pane.</p>

<pre><code class="language-bash">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"
  }'</code></pre>

<pre><code class="language-json">{
  "html": "&lt;h1 id=\"shipping-docs-faster\"&gt;Shipping docs faster&lt;/h1&gt;\n&lt;pre class=\"shiki github-dark\"&gt;...&lt;/pre&gt;"
}</code></pre>

<h2 id="shell-example">Shell Example</h2>
<p>Shell examples should be safe to paste as-is. Show flags, URLs, and expected output in separate blocks when needed.</p>

<pre><code class="language-bash">pnpm --filter @pobal-os/engine validate:routes
pnpm --filter @pobal-os/engine build
npx wrangler deploy</code></pre>

<h2 id="http-example">HTTP Example</h2>
<p>For APIs, pair the request with the response. That makes the docs useful even before a reader opens their own tooling.</p>

<pre><code class="language-http">GET /api/v1/search?q=bulkhead&amp;limit=3&amp;type=inform&amp;visibility=external
Accept: application/json</code></pre>

<pre><code class="language-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
  }
}</code></pre>

<h2 id="markdown-example">Markdown Example</h2>
<p>When documenting authoring, include the exact Markdown a content editor would type.</p>

<pre><code class="language-markdown">## 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.</code></pre>

<div class="docs-callout docs-callout--success">
<p><strong>Rule of thumb:</strong> If a reader would need to invent sample data before they can try the feature, the example is still too abstract.</p>
</div>
</div>