Bulkhead Docs

Pobal OS engine reference

Reusable blocks for the editor and published docs

The Blocks menu in the node editor and the published docs renderer now share one catalog of reusable patterns. This page is the engine-owned reference for what ships by default, how it should be used, and what authors should reach for first.

15 shared blocks in the default catalog
6 categories surfaced in the Blocks dropdown
1 shared source of truth for HQ and the richer MDX editor

Block menu coverage

These groups come from the same catalog the editor dropdown consumes. The point is to make the reusable docs system easy to discover in authoring, not bury it behind one-off toolbar icons.

Callouts

5 blocks
  • Note callout

    Add supporting context without interrupting the main flow.

    Good for prerequisites, caveats, and author guidance.

    Source: Mintlify / Docusaurus

  • Tip callout

    Highlight the preferred or most efficient path.

    Useful for product defaults, best practices, and shortcuts.

    Source: Mintlify / Docusaurus

  • Warning callout

    Flag migrations, breaking changes, or risky actions.

    Best for irreversible actions and high-impact caveats.

    Source: Mintlify / Docusaurus

  • Info callout

    Surface neutral, factual context near the content.

    Works well for compatibility notes and version guidance.

    Source: Mintlify / Docusaurus

  • Generic callout

    A generic callout that can be styled with any variant.

    Use when no specific callout variant fits.

    Source: Mintlify / Docusaurus

Guides

4 blocks
  • Tabs

    Switch between alternative install paths, SDKs, or roles.

    Useful when a page needs multiple valid paths without duplication.

    Source: Mintlify / Fern

  • FAQ accordion

    Collapse secondary detail until readers need it.

    Good for FAQ sections, troubleshooting, and migration notes.

    Source: Mintlify / Docusaurus

  • Procedure steps

    Capture a linear how-to flow with numbered instructions.

    Best for onboarding, setup, and operational runbooks.

    Source: Docusaurus / docs.bulkheados.com

  • Progress indicator

    Show completed, current, and upcoming stages in a docs journey.

    Useful for migrations, checklists, onboarding, and release paths.

    Source: Zendesk Garden / Carbon

Reference

2 blocks
  • Code group

    Pair the same example across languages or request styles.

    Useful for SDK parity and request/response examples.

    Source: Mintlify / Fern

  • API request and response

    Package request and response examples into a single reusable block.

    Useful for endpoint docs that need an immediate copy-paste path.

    Source: Fern / Mintlify

Navigation

1 blocks
  • Quick links grid

    Create a dense navigation surface for docs hubs and landing pages.

    Useful for quickstarts, references, tutorials, and policy hubs.

    Source: Mintlify / Fern

Product loops

2 blocks
  • Page feedback prompt

    Capture whether the page helped and feed that signal back into docs.

    Useful at the bottom of guides, setup docs, and support content.

    Source: docs.bulkheados.com

  • Community thread

    Show social proof or shared learnings below the docs content.

    Useful for release notes, migration guides, and examples.

    Source: docs.bulkheados.com

Transclusion

1 blocks
  • Node embed

    Pull a reusable canonical answer into multiple docs pages.

    Useful for policies, shared snippets, and reference reuse.

    Source: docs.bulkheados.com

Docs product patterns

The shared catalog is built around the patterns that show up repeatedly in Fern, Mintlify, Docusaurus, and the existing docs.bulkheados.com surface: clear defaults, fast scanning, and reusable guidance instead of hand-built page chrome.

Table stakes

  • Callouts, steps, tabs, accordions, and code groups should be one click away in the editor.
  • Shared docs blocks must render with the same contract in preview, published HTML, and the static Astro path.
  • Docs navigation patterns should stay tenant-agnostic and rely on shared engine tokens, not tenant theme overrides.

Differentiators

  • Progress indicators make migrations, onboarding, and release paths easier to scan than plain numbered steps.
  • Quick links grids, node embeds, and feedback loops turn documentation into a reusable product surface instead of a dead text page.
  • Reusable request and response templates reduce the gap between authored guides and reference docs.

Avoid

  • Do not ship shared docs blocks that depend on OS-level color-scheme media queries alone.
  • Do not fork the editor block list per tenant when the pattern belongs in the shared engine.
  • Do not link authors to routes that are not actually available in the current engine or HQ surfaces.

Live examples

These examples use the same shared primitives that authored content uses, including the new progress indicator pattern for migrations and step-driven workflows.

Callouts

Use semantic callouts for context, defaults, migration warnings, and compatibility notes.

Background context
Notes are for context that helps the reader without interrupting the main flow.
Preferred path
Tips help the author promote the default or quickest path without restating the whole guide.
Migration boundary
Use warnings for irreversible steps, breaking changes, and dependency boundaries.
Compatibility
Info blocks are a better fit for neutral version details and factual environment notes.

Procedures and progress

Use numbered steps for task flow and a progress indicator when readers need to track stage status.

Create the draft
Start with the shared snippet blocks instead of writing ad hoc HTML.
Review the preview
Check that published output and author preview match before you ship.

Release path

  1. Connect the domain
    Routing and certificates are already configured.
  2. Validate the preview
    Review the rendered page before publishing it.
  3. Publish the page
    Ship once content, metadata, and feedback hooks are ready.

Reference patterns

Tabs and grouped code blocks let one page support multiple runtimes without duplicating prose.

FAQ and navigation

Accordions handle secondary detail. Quick-link cards work better than dense prose for hub pages.
QS
Quickstart
Start with the setup path.
API
API
Browse endpoint contracts.
OPS
Ops
Review runbooks and maintenance guides.

Transclusion and feedback

Node embeds keep canonical answers reusable. Feedback components close the loop after the page is published.

Refund policy
shared/refund-policy

Feedback

Was this block catalog useful?

Capture a fast signal so the shared catalog evolves around real author needs.

No feedback recorded yet.

No response recorded yet.

Ready-to-insert snippets

These are the exact snippet contracts authors can insert from the shared dropdown today. They are useful defaults for migration docs, request and response references, feedback capture, and transclusion.

Guides

Progress indicator

Useful for migrations, checklists, onboarding, and release paths.

Source: Zendesk Garden / Carbon

Jump to live example

Insertion preview

Launch path

  1. Review changes
    The release checklist is complete.
  2. Validate preview
    Confirm the published output is ready.
  3. Publish docs
    Ship after review finishes. 
<ProgressIndicator>
  <ProgressStep title="Connect domain" status="complete">
    DNS is verified and edge routing is active.
  </ProgressStep>
  <ProgressStep title="Review preview" status="current">
    Validate the rendered output before you publish.
  </ProgressStep>
  <ProgressStep title="Publish changes" status="upcoming">
    Ship the page when content and metadata are ready.
  </ProgressStep>
</ProgressIndicator>

Product loops

Page feedback prompt

Useful at the bottom of guides, setup docs, and support content.

Source: docs.bulkheados.com

Jump to live example

Insertion preview

<PageFeedback
  pageKey="docs/editor-preview"
  title="Was this guide useful?"
  description="Capture a fast signal directly on the page."
/>

Transclusion

Node embed

Useful for policies, shared snippets, and reference reuse.

Source: docs.bulkheados.com

Jump to live example

Insertion preview

Refund policy
shared/refund-policy
<NodeEmbed id="domain/published-node-id" />

Reference

API request and response

Useful for endpoint docs that need an immediate copy-paste path.

Source: Fern / Mintlify

Jump to live example

Insertion preview

<Tabs>
  <Tab label="Request">
    <CodeGroup>
      <CodeBlock label="cURL" language="bash">
```bash
curl -X POST https://docs.bulkheados.com/api/v1/editor-preview \
  -H "Content-Type: application/json" \
  -d '{"markdown":"# Hello world","theme":"light"}'
```
      </CodeBlock>
    </CodeGroup>
  </Tab>
  <Tab label="Response">
    <CodeGroup>
      <CodeBlock label="JSON" language="json">
```json
{
  "html": "<h1 id=\"hello-world\">Hello world</h1>"
}
```
      </CodeBlock>
    </CodeGroup>
  </Tab>
</Tabs>