Quickstart

You already have a working docs site — this project is it. In the next five minutes you'll run it locally, change how it looks, add a page, and publish it. Everything is driven by two things: docs.json (settings) and content/docs/ (your Markdown).

Before you begin

You'll need Node.js 20 or newer and the project you got from fiskil init. Everything runs locally — nothing is published until you choose to publish.

Open the project in your editor now. The two paths you'll touch most are docs.json at the root and the content/docs/ folder next to it.

Run your site locally

From the project folder, install dependencies and start the dev server:

npm install
npx fiskil dev

Open http://localhost:3000. The site reloads as you edit — save a file and the browser updates.

The command failed or the page won't load

Make sure you're on Node 20+ (node --version) and running from the folder that contains docs.json. If port 3000 is busy, stop whatever is using it — the dev server always serves on 3000.

Make your first change

Pick a tab. Both changes show up instantly in the browser.

Open docs.json

Change the site name and brand color:

{
  "name": "Acme",
  "theme": { "colors": { "primary": "#0EA5E9" } }
}

Save and look

The header, buttons, links, and dark mode all pick up your brand color immediately — no rebuild needed.

Create the file

Add content/docs/example/guides/get-started/hello.mdx:

---
title: Hello
description: My first page
---

It works!

Put it in the sidebar

Add "hello" to the pages list in content/docs/example/guides/get-started/meta.json. The page appears in the sidebar in that order.

Publish your site

When you're ready to go live, publish through the Fiskil docs platform:

npx fiskil publish

This builds your site and deploys it. Run npx fiskil validate any time first — the build refuses to run on a broken docs.json, so mistakes never reach readers.

You can serve the site on your own domain. See Publish for custom domains and preview deploys.

Next steps

How it works

The mental model behind docs.json and content.

Components

Callouts, steps, tabs, cards, and more.

Add your API

Turn an OpenAPI file into a live reference.

Customize the theme

Colors, light and dark, accents.