Publishing Docs

DocPlatform can serve your documentation as a website — complete with a navigation sidebar, syntax highlighting, and SEO metadata. No separate static site generator required. By default, published docs are visible only to authenticated workspace members. Admins can opt in to make them fully public.

How publishing works

Published docs are served at /p/{workspace-slug}/{page-path}:

http://localhost:3000/p/my-docs/              → docs/index.md
http://localhost:3000/p/my-docs/quickstart    → docs/quickstart.md
http://localhost:3000/p/my-docs/api/auth      → docs/api/auth.md

Pages are rendered from Markdown to HTML on request using goldmark (CommonMark-compliant) with Chroma syntax highlighting (Dracula theme) for code blocks.

Page status lifecycle

Pages have a status field that controls their visibility:

Set the status in frontmatter:

---
title: My Page
status: published    # draft, published, or archived
publish: true        # shorthand — equivalent to status: published
---

The publish: true shorthand and status: published are equivalent. Use whichever you prefer.

Enable publishing

Per-page

Set published: true in the page’s frontmatter:

---
title: API Authentication
description: How to authenticate with the API.
published: true
---

Or toggle the Published switch in the frontmatter form of the web editor.

Workspace-level default

Set a workspace-level default so new pages are published automatically:

# .docplatform/config.yaml
publishing:
  default_published: true
  require_explicit_unpublish: false

Themes

DocPlatform ships with 7 built-in themes for published documentation:

Set the theme in your workspace config:

# .docplatform/config.yaml
theme:
  mode: auto    # light, dark, or auto (follows system preference)
  accent: blue  # or use a named theme

Each theme supports automatic light/dark mode switching based on the visitor’s system preference when mode: auto is set.

Published site features

Navigation

The published site generates a sidebar navigation from your page hierarchy. The order matches the sidebar in the web editor.

To customize navigation order, adjust the navigation section in your workspace config:

# .docplatform/config.yaml
navigation:
  - title: "Getting Started"
    path: "getting-started/index.md"
    children:
      - title: "Installation"
        path: "getting-started/installation.md"
      - title: "Quickstart"
        path: "getting-started/quickstart.md"

Syntax highlighting

Code blocks are highlighted using Chroma (Dracula theme). Over 200 languages are supported.

Specify the language after the opening triple backticks:

```python
def hello(name: str) -> str:
    return f"Hello, {name}!"
```

SEO

DocPlatform generates SEO metadata automatically from your page frontmatter:

Access control

By default, published docs require viewer authentication — only logged-in workspace members can read them. This protects your documentation from accidental public exposure.

To make a workspace’s published docs fully public (world-readable without login), a workspace admin must explicitly set the visibility to “public” in the workspace settings:

PUT /api/v1/workspaces/:id/admin/settings
{ "visibility": "public" }

When visibility is “authenticated”:

• Visitors who are not logged in are redirected to /#/login?next=<url>
• After signing in, they are returned to the page they requested
• Any workspace member (any role, including Viewer) can read published pages
• Non-members are redirected away even after logging in
• Sitemaps, robots.txt, and RSS feeds are also protected

Server-level override: The PUBLISH_REQUIRE_AUTH=true environment variable forces authentication on all published sites, regardless of their per-workspace visibility setting. This is useful for fully private installations where no documentation should ever be public.

Built-in components

Published docs support 15 custom components that render as rich, interactive elements. Here are the most commonly used ones (see Markdown & Components for the full list):

Callout

:::callout[info]
This is an informational callout.
:::

:::callout[warning]
Be careful with this operation.
:::

:::callout[danger]
This action is irreversible.
:::

:::callout[tip]
Pro tip: use keyboard shortcuts for faster editing.
:::

Types: info, warning, danger, tip, note

Tabs

:::tabs
::tab[npm]
npm install docplatform
::
::tab[yarn]
yarn add docplatform
::
::tab[pnpm]
pnpm add docplatform
::
:::

Accordion

:::accordion[How does sync work?]
DocPlatform uses a hybrid git engine that combines go-git for small repositories
with native git CLI for large ones. Changes are synced via polling or webhooks.
:::

Cards

:::cards
::card[Getting Started, link="/getting-started"]
Install and configure DocPlatform in under 10 minutes.
::
::card[User Guide, link="/guides/editor"]
Learn the web editor, git sync, and publishing features.
::
:::

Steps

:::steps
::step[Install]
Download the binary or pull the Docker image.
::
::step[Initialize]
Run `docplatform init` to create your workspace.
::
::step[Start]
Run `docplatform serve` and open the browser.
::
:::

API Block

:::api[GET /api/v1/content/{workspace}/{...path}]
Retrieve a single page by workspace and path.

**Parameters:**
- `workspace` (path, required) — Workspace slug
- `path` (path, required) — Page file path

**Response:** `200 OK`
```json
{
  "page_id": "01HJKL...",
  "title": "Getting Started",
  "content": "..."
}

:::

## Custom domains

DocPlatform supports per-workspace custom domains with automatic TLS provisioning via Caddy integration.

### Setup

1. **Configure Caddy** as your reverse proxy with the on-demand TLS ask endpoint:

{ on_demand_tls { ask http://localhost:3000/internal/caddy/ask } }

:443 { tls { on_demand } reverse_proxy localhost:3000 }

2. **Set environment variables:**

```bash
export BASE_DOMAIN=docs.yourcompany.com
export CADDY_ADMIN_URL=http://localhost:2019
export CADDY_ASK_SECRET=your-shared-secret

3. Assign a custom domain to a workspace via the API or admin UI:

curl -X PUT /api/v1/workspaces/{id}/custom-domain \
  -H "Authorization: Bearer ..." \
  -d '{"domain": "docs.yourcompany.com"}'

4. Point DNS — Add a CNAME or A record pointing to your DocPlatform server.

DocPlatform verifies DNS automatically and provisions TLS certificates on first request. No manual certificate management required.

Managing custom domains

Super admins can manage all domains from the admin panel:

Caching

Published pages are cached for performance:

The cache key is based on the page’s content hash. When content changes, the ETag changes automatically and cached versions are invalidated.

Asset URL rewriting

In the web editor, assets use relative paths (assets/screenshot.png). In published docs, these are automatically rewritten to absolute paths (/p/{slug}/assets/screenshot.png) so images and files load correctly at any URL depth.

Static export

Export your published docs as a self-contained static HTML ZIP for CDN deployment or offline distribution.

Via CLI

docplatform export --workspace my-docs --output ./my-docs-export.zip

Via API

GET /api/v1/workspaces/{id}/export

Returns a ZIP file containing:

• Rendered HTML for all published pages
• sitemap.xml and robots.txt
• Sidebar navigation and CSS
• Ready to deploy to any static file host (Netlify, Vercel, S3, GitHub Pages)

Preview before publishing

Preview published docs locally without building a static export:

docplatform preview --workspace my-docs --port 4000

This starts a lightweight local server that renders pages in real-time — useful for reviewing changes before deploying.

Pages with published: false are still accessible to authenticated workspace members at the /p/ path — they’re just excluded from the public navigation and sitemap.