# 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](https://astro.build), 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.

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/docs/quickstart/">
    Install Writedocs and scaffold your first site in under a minute.
  </Card>
  <Card title="CLI Reference" icon="terminal" href="/docs/cli/">
    Every command and flag: `dev`, `build`, `init`.
  </Card>
  <Card title="Configuration" icon="settings" href="/docs/configuration/overview/">
    The full `writedocs.json` reference — theme, navigation, topbar, and more.
  </Card>
  <Card title="API Reference" icon="webhook" href="/docs/openapi/overview/">
    Turn an OpenAPI spec into an interactive, try-it-enabled API reference.
  </Card>
</CardGroup>

## 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`.

<Callout type="tip">
  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.
</Callout>

<Callout type="note">
  `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 or is listed in `navigation`; any other file 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](/docs/configuration/navigation-basics/#pages-can-live-anywhere) for details.
</Callout>

## What's included

- **Flexible navigation** — a flat sidebar, or tabs/versions/languages/products/dropdowns, nestable to any depth. See [Navigation basics](/docs/configuration/navigation-basics/) and [Navigation: tabs, versions, languages, products, dropdowns](/docs/configuration/navigation-advanced/).
- **A standard MDX component set** — callouts, cards, tabs, accordions, steps, code groups — available in every page with no imports. See [Components](/docs/content/components/).
- **Rich code blocks** — dual light/dark syntax highlighting, line highlighting, diffs, focus, word highlighting, titles, and collapsible blocks. See [Code blocks](/docs/content/code-blocks/).
- **Built-in search** — every build is indexed automatically; no configuration or external service needed. See [Search](/docs/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)](/docs/openapi/overview/).
- **Light/dark theming** — automatic dark mode toggle, with per-site color, logo, and code-block-theme overrides. See [Styles](/docs/configuration/styles/).

Start with the [quickstart](/docs/quickstart/) to get a site running locally.