# 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](./install.md).

::::steps
## Create site.json

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

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

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

```json title="rocket/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" }] }
}
```

## Write a page

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

```md title="rocket/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.
```

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

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

## 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](./deployment.md).
::::

:::note[What next.]
Read [Project layout](./project-layout.md) to add sections, versions and a changelog, and
[Directives](../writing/directives.md) for everything you can write in a page.
:::
