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.
{
"$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.
{
"$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.
---
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
$ 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
$ npx docsp devOpen 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
$ npx docsp buildThe static site is in dist/, with the search index in dist/pagefind/. Serve that folder from the root of a
domain; see Deployment.
What next. Read Project layout to add sections, versions and a changelog, and Directives for everything you can write in a page.