Skip to content
docsp
On this page

A first site in 5 minutes

Create a portal with one project and one page, preview it and build it.

You will create a site with one project called Rocket and one guide page, run it locally and build it into dist/. You need docsp and Astro installed, as described in Install.

1. Create site.json

site.json sits next to package.json. It names the site, lists the projects and sets the languages.

JSONsite.json
{
  "$schema": "./node_modules/@fabricators/docsp/schema/site.schema.json",
  "name": "Acme docs",
  "projects": [{ "path": "rocket" }],
  "i18n": { "default": "en", "locales": [{ "code": "en", "label": "English" }] }
}

2. Create the project

Each entry in projects is a folder with a project.json. The id is the first URL segment of the project, and each section in nav.sections is a tab and a folder of pages.

JSONrocket/project.json
{
  "$schema": "../node_modules/@fabricators/docsp/schema/project.schema.json",
  "id": "rocket",
  "name": "Rocket",
  "tagline": "Launch scheduling API",
  "theme": { "accent": "teal" },
  "nav": { "sections": [{ "id": "guides", "label": "Guides", "kind": "guides" }] }
}

3. Write a page

Pages live in docs/<locale>/<section>/. The file name is the URL slug.

mdrocket/docs/en/guides/quickstart.md
---
title: Quickstart
description: Schedule your first launch.
---

:::note[Before you start.]
You need an API key.
:::

Send a launch request with your key.

4. Check the configuration

Terminal
$ npx docsp check
ok  rocket/project.json  rocket  lowest theme contrast 4.58:1
Content is valid: 2 page(s).
Configuration is valid: 1 project(s).

The page count includes the portal home. check validates both JSON files against the schemas, checks the contrast of the project color and reads every page. A mistake stops it with the file, the field and the expected value.

5. Start the development server

Terminal
$ npx docsp dev

Open the address Astro prints (by default http://localhost:4321/). The portal lists Rocket, and /rocket/guides/quickstart/ shows the page. Changes to Markdown, YAML and CSS files reload the page.

6. Build the site

Terminal
$ npx docsp build

The static site is in dist/, with the search index in dist/pagefind/. Serve that folder from the root of a domain; see Deployment.

Note:

What next. Read Project layout to add sections, versions and a changelog, and Directives for everything you can write in a page.

↑ ↓ to move↵ to openSearching docsp