Introduction

Welcome to Writedocs — this page is rendered from docs/index.mdx, styled and wrapped by the layout using writedocs.json. Everything you see here, from the sidebar to the color of the links, comes from that one config file plus the Markdown/MDX files in docs/.

What is Writedocs

Writedocs is a static site generator purpose-built for documentation. You write content as Markdown/MDX files, describe navigation and theme in a single writedocs.json, and running writedocs build turns that into a fully static site — no server required at runtime, just HTML, CSS, and a small amount of JS for interactive components like tabs.

It sits in the same category as Docusaurus, VitePress, and Starlight, and is built on top of Astro under the hood.

Why a static site generator

A few properties fall out of the static approach that matter for docs specifically:

• Pages load fast, because there’s no server-side rendering happening per request — everything is prebuilt.
• The output is a folder of files, so hosting is trivial: any static host, CDN, or even a plain file server works.
• There’s no database and no runtime dependency to keep patched or paying for.

Why not just Markdown files in a repo

Plain Markdown rendered by GitHub or a wiki gets you text, but not navigation, theming, versioning, or interactive components. writedocs.json plus the MDX component library (see the Components guide) fills that gap without requiring you to write any HTML or JavaScript yourself.

Quick example

A minimal writedocs.json looks like this:

{
  "name": "My Docs",
  "navigation": [
    { "group": "Getting Started", "pages": ["index", "getting-started"] }
  ]
}

That’s enough to get a working site with a sidebar containing two links, once docs/index.mdx and docs/getting-started.mdx exist.

Where to go next

This fixture exists to exercise every component and heading level Writedocs supports, so if something looks broken here, it’s a bug in the renderer, not the content.