Writing Docs

How to add, organize, and illustrate pages in this documentation.

Docs are plain Markdown files in content/docs/ in the repo — no CMS. They render through the same pipeline as the blog (syntax highlighting, copy buttons, "On this page" TOC). To publish a page: commit the file and redeploy.

Adding a page

Create content/docs/<name>.md, or content/docs/<folder>/<name>.md to place it in a sidebar group. An index.md inside a folder is that folder's landing page.

---
title: My New Page
description: One sentence — used for SEO meta and sidebar search.
order: 42
---
 
Your Markdown content…

Frontmatter reference

Key Required What it does
title yes Page H1, sidebar label, and meta title
description yes Meta description + sidebar search snippet
order yes Sort position (lower = higher). See numbering scheme below
group no Overrides the sidebar group label (default: humanized folder name — needed when that's wrong, e.g. web-gtm → "GTM Web")
series no Pages sharing a series id form a reading sequence: they get prev/next chapter navigation, ordered by order across all groups
section no Top-level sidebar section ("Learn" / "Pixel Logic Server" / "Handbook"). Defaults from the page's top folder via SECTION_BY_FOLDER in lib/docs.js; set explicitly to override

Sections & numbering

The sidebar is organized into top-level sections (set by section, defaulting from the top folder via SECTION_BY_FOLDER in lib/docs.js):

  • Pixel Logic Server — customer-facing product docs (content/docs/pixel-logic-server/)
  • Learn — the GTM Guide + ecosystem (foundations, web-gtm, server-gtm, ecosystem)
  • Handbook — internal team how-tos

order sorts pages within their section/group (lower = higher). Because sections control top-level placement, the same order range can be reused per section:

  • Pixel Logic Server product docs: 1–29 (series: pixel-logic-server)
  • GTM Guide chapters (Learn): 1–29 (series: gtm-guide)
  • Team Handbook: 100+

⚠️ Product docs are customer-facing. Anything under pixel-logic-server/ must read like external product documentation (Stape-style): explain how to use the product, never how it's built. Do not name or describe internal infrastructure (the agent/proxy, container internals, Traefik/Dokploy, the VPS, URL-obfuscation mechanics, tokens). Use customer terms: "your Pixel Logic Server", "Server URL", "preview environment".

Diagrams

  • ASCII diagrams (fenced ```text blocks) for simple flows and box-and-arrow sketches. They're diffable, theme-proof, and render everywhere.
  • SVG images (committed to public/docs-assets/, referenced as ![alt text](/docs-assets/my-diagram.svg)) only where a diagram genuinely needs layout, color, or density that ASCII can't carry. Use neutral mid-tone colors and transparent backgrounds so they work on light and dark themes.

What you get for free

  • Sidebar entry (grouped + ordered) and client-side search
  • "On this page" TOC when the page has ≥ 2 headings
  • sitemap.xml entry and SEO meta from the frontmatter
  • Syntax-highlighted code blocks with copy buttons
  • Prev/next chapter navigation when series is set

Local preview

npm run dev → http://localhost:3000/docs. Doc pages read straight from the filesystem — no database needed, edits hot-reload.