Pages JSON format

How to author content: the write body is always { path, kind, projectId?, data } — only data changes shape per kind.

Writing a page

Create or replace content with POST /api/docs/admin/pages. Every request has the same envelope; the data field carries the kind-specific payload.

request.http

http

POST /api/docs/admin/pages
Content-Type: application/json

{
  "path": "/my-lib/intro",   // unique, leading slash
  "kind": "section",          // any string
  "projectId": "my-lib",      // optional
  "data": { }                  // the payload, by kind (below)
}

kind: project

project.json

json

{
  "path": "/my-lib",
  "kind": "project",
  "projectId": "my-lib",
  "data": {
    "id": "my-lib", "name": "My Lib", "abbr": "ML", "color": "#3b82f6",
    "category": "packages", "version": "1.0.0", "tagline": "Does the thing",
    "tags": ["http"], "pages": 2, "updated": "2026-06-29",
    "install": [{ "label": "npm", "lang": "bash", "code": "npm i my-lib" }],
    "features": [{ "icon": "⚡", "title": "Fast", "desc": "Very" }],
    "sidebar": [{ "title": "Start", "items": [{ "id": "intro", "label": "Intro" }] }]
  }
}

kind: section

section.json

json

{
  "path": "/my-lib/intro",
  "kind": "section",
  "projectId": "my-lib",
  "data": {
    "title": "Introduction",
    "crumbs": [{ "label": "My Lib", "href": "/my-lib" }, { "label": "Introduction" }],
    "lead": "A short intro.",
    "blocks": [
      { "type": "h2", "id": "why", "text": "Why" },
      { "type": "p", "md": "Inline `code`, **bold**, and [links](/my-lib)." },
      { "type": "code", "file": "x.ts", "lang": "ts", "code": "const x = 1;" },
      { "type": "callout", "kind": "tip", "title": "Tip", "md": "Be nice." },
      { "type": "list", "items": ["one", "two"] }
    ],
    "toc": [{ "id": "why", "text": "Why", "level": 2 }],
    "prev": null, "next": null
  }
}

kind: api

api.json

json

{
  "path": "/my-lib/api",
  "kind": "api",
  "projectId": "my-lib",
  "data": {
    "title": "API",
    "lead": "The surface.",
    "entries": [
      {
        "name": "get", "kind": "function",
        "sig": "get<T>(path): Promise<T>", "desc": "Typed GET.",
        "props": [{ "name": "path", "type": "string", "req": true, "desc": "URL" }]
      }
    ]
  }
}

kind: components

Here data is a JSON array, not an object.

components.json

json

{
  "path": "/my-lib/components",
  "kind": "components",
  "projectId": "my-lib",
  "data": [
    {
      "id": "button", "title": "Button", "name": "Button",
      "desc": "A clickable button.",
      "code": { "svelte": "<button><slot/></button>", "razor": "<button>@ChildContent</button>" }
    }
  ]
}

kind: cheatsheet

cheatsheet.json

json

{
  "path": "/cheatsheet/my-lib",
  "kind": "cheatsheet",
  "projectId": null,
  "data": {
    "title": "My Lib",
    "crumbs": [{ "label": "Cheatsheets", "href": "/" }, { "label": "My Lib" }],
    "lead": "Quick reference.",
    "groups": [
      { "title": "Basics", "icon": "🌱", "rows": [["doThing()", "Does the thing"]] }
    ]
  }
}