Example DocsExample Docs

Getting Started

This page walks through installing Writedocs, creating a project, and running it locally, end to end.

Prerequisites

You’ll need:

  • Node.js 20.3 or newer
  • A package manager (npm, pnpm, or yarn all work)

Writedocs is currently distributed as a package you install directly into a project, not a global CLI. That’s why every command below is run through npm run or npx, not a bare writedocs command.

Installation

Using npm

npm install writedocs

Using pnpm

pnpm add writedocs

Either way, you end up with the writedocs CLI available in your project’s node_modules/.bin, and callable via npm run scripts or npx writedocs.

Project structure

A Writedocs project only needs two things: a writedocs.json and a docs/ folder.

my-docs/
├── writedocs.json
└── docs/
    ├── index.mdx
    ├── getting-started.mdx
    └── guides/
        └── components.mdx

Run the scaffolder to generate a starting point automatically instead of creating these by hand:

npx writedocs init ./my-docs

Configuration

Every Writedocs site is configured through writedocs.json. The fields you’ll touch first:

FieldTypeRequiredDescription
namestringyesSite name, shown in the browser tab and topbar.
navigationarrayyesThe sidebar structure — see Configuration for the full shape.
styles.colors.primarystringnoAccent color used for links, active nav items, and step markers.
topbar.linksarraynoLinks shown in the top-right of every page.

See the Configuration guide for every field in detail.

Running the dev server

Install

Run npm install if you haven’t already — this installs Writedocs and its dependencies (Astro, MDX support, and so on) into node_modules.

Configure

Create a writedocs.json and a docs/ folder, or run npx writedocs init to scaffold one.

Preview

Run npx writedocs dev to start a local dev server with hot reload, and open the URL it prints (http://localhost:4321 by default).

Once the dev server is running, edits to any .mdx file or to writedocs.json itself are picked up automatically — no restart required for content changes.

Building for production

When you’re ready to deploy:

npx writedocs build

This writes a fully static site into dist/ inside your content directory. The output is plain HTML, CSS, and JS — it can be served by any static host, with no Writedocs-specific runtime required.

Deploying dist/ is exactly like deploying any other static site: point your host (Netlify, Cloudflare Pages, an S3 bucket, nginx, whatever you already use) at that folder.

Next steps

🧩

Components

See every MDX component available, with live examples.

✍️

Writing content

Markdown/MDX authoring conventions used throughout this fixture.