Writing docs

Writing pages

How this site is built — file layout, frontmatter, navigation, and local preview.

This documentation site is plain Markdown compiled to static HTML. There is no CMS and no runtime framework; if you can edit a .md file you can ship a docs change.

Repository layout

Text
docs.json          site config: branding, navbar, navigation
content/           every page, one .md file per page
  index.md         → /
  quickstart.md    → /quickstart/
  connections/
    postgresql.md  → /connections/postgresql/
public/            static assets copied verbatim
  images/          → /images/…
src/               styles.css and app.js
scripts/           the generator (build.mjs, dev.mjs)
dist/              build output — generated, not committed

The URL of a page is its path under content/, minus the extension. index.md becomes the site root.

Frontmatter

Every page starts with a YAML block.

Markdown
---
title: PostgreSQL
description: Connect a PostgreSQL database over Chartizer Cloud or a local agent.
navTitle: Postgres
---
Key Required Purpose
title yes <h1>, browser title, search result title
description recommended Subtitle under the <h1>, meta description, search snippet
navTitle no Shorter label for the sidebar when title is long
updated no Overrides the automatic “last updated” date

Do not write your own `# Heading`

The title frontmatter already renders the <h1>. Start the body at ## — otherwise the page gets two competing top-level headings and the table of contents doubles up.

Add a page to the navigation

A file in content/ does nothing until it is listed in docs.json. Pages appear in the sidebar in the order they are listed.

docs.json
{
  "navigation": {
    "groups": [
      {
        "group": "Data catalogue",
        "icon": "database",
        "pages": [
          "data-catalogue/overview",
          "connections/postgresql"
        ]
      }
    ],
    "hidden": [
      {
        "group": "API reference",
        "pages": ["api/authentication"]
      }
    ]
  }
}
  • Groups are the collapsible sections in the sidebar, in the order listed. icon accepts any name from the built-in icon set (database, plug, folder, book, key, code, rocket, lock, sheet, globe, file, map, layers, sync, sparkles, terminal, table, users, chart, sliders, shield, share, message, mail).
  • Pages are paths under content/, without .md.
  • hidden groups build normally — they are linkable, searchable, and get prev/next — but never appear in the sidebar. Use it for reference material that would otherwise clutter the nav, and link to it from the footer or from within a page.

There is one sidebar, always visible

The nav is a flat list of groups with no tab switcher above it, so every section is one click away from every page.

Missing files warn, they don't crash

Listing a page that does not exist prints ! missing content for: … during the build and skips it. The rest of the site still builds.

Internal links are absolute from the site root and keep their trailing slash:

Markdown
See [Mappings](/data-catalogue/mappings/) for the full flow.

Images live in public/images/ and are referenced from the root. They are lazy-loaded and open in a lightbox on click:

Markdown
![Data catalogue overview](/images/catalogue-overview.png)

Wrap a screenshot in a frame to get a border and a caption:

Markdown
::::frame The Overview tab after a successful sync
![Data catalogue overview](/images/catalogue-overview.png)
::::

Put screenshots at 2× and let CSS scale them

Retina screens are the common case. A 2000px-wide capture displayed at 1000px stays crisp.

Preview locally

Bash
npm install     # once
npm run dev     # http://localhost:4321, rebuilds and reloads on save

Build the static site for deployment:

Bash
npm run build   # writes dist/

dist/ is plain HTML, CSS, JS, and images — serve it with anything: nginx, Caddy, S3, GitHub Pages, Netlify.

Hosting under a subpath

If the site is served from https://chartizer.com/docs rather than a domain root, set baseUrl once and every link, asset, and search result adjusts:

docs.json
{
  "baseUrl": "/docs"
}

Style conventions

  • One <h2> per idea; the table of contents is generated from <h2> and <h3>.
  • Lead with what the reader is trying to do, not with how the feature is built.
  • Prefer a table over three paragraphs describing the same three options.
  • Use callouts sparingly — a page where everything is highlighted highlights nothing.
  • Reserve :::danger for actions that lose data or expose it.

See Components for everything you can put on a page.