WritedocsWritedocs

Introduction

Writedocs is a static site generator for documentation: a writedocs.json config file plus a folder of Markdown/MDX in, a fully static site out. It’s built on Astro, in the spirit of Docusaurus and Mintlify — you write content and configure navigation/theme, and Writedocs handles rendering, routing, search, and (optionally) an interactive API reference.

Quickstart

Install Writedocs and scaffold your first site in under a minute.

CLI Reference

Every command and flag: dev, build, init.

Configuration

The full writedocs.json reference — theme, navigation, topbar, and more.

API Reference

Turn an OpenAPI spec into an interactive, try-it-enabled API reference.

How a project is structured

A Writedocs project is just two things:

my-docs/
├── writedocs.json          # nav, theme, metadata
├── index.mdx           # home page, served at "/"
└── docs/
    ├── getting-started.mdx
    └── guides/
        └── components.mdx

writedocs.json describes the site: its name, theme colors, and navigation tree. Every page referenced in navigation is a .md or .mdx file, addressed by its path relative to the project root with the extension stripped — docs/guides/components.mdx is referenced as docs/guides/components.

Nothing else is required. No framework code, no node_modules, no build config lives in your project — Writedocs itself is installed as a dependency (or run via npx) and does all of the rendering.

docs/ is a convention, not a requirement — it’s just a folder, scanned the same way as any other. A .md/.mdx file becomes a page anywhere in your project (the root itself, or any other folder, docs/ included) as long as it has a frontmatter block; a file with no frontmatter is left alone. The home page is whichever page’s file id is index — in practice, index.mdx at the project root, since a nested index.mdx (docs/getting-started/index.mdx, say) drops its own /index segment instead and serves at its folder’s own path. See Navigation basics for details.

What’s included

  • Flexible navigation — a flat sidebar, or tabs/versions/languages/products/dropdowns, nestable to any depth. See Navigation basics and Navigation: tabs, versions, languages, products, dropdowns.
  • A standard MDX component set — callouts, cards, tabs, accordions, steps, code groups — available in every page with no imports. See Components.
  • Rich code blocks — dual light/dark syntax highlighting, line highlighting, diffs, focus, word highlighting, titles, and collapsible blocks. See Code blocks.
  • Built-in search — every build is indexed automatically; no configuration or external service needed. See Search.
  • OpenAPI-powered API reference — point a navigation group at an OpenAPI spec and get a full reference with a live “Try it” playground, generated automatically. See API Reference (OpenAPI).
  • Light/dark theming — automatic dark mode toggle, with per-site color, logo, and code-block-theme overrides. See Theme.

Start with the quickstart to get a site running locally.