# apigenie-docs build

Source: https://apigenie.pl/docs/reference/doc-components/docs-build
Part of the reference of [@mykulyak/apigenie-docs](https://apigenie.pl/docs/reference/doc-components.md).
Its other pages: [apg-api-reference and apg-spec](https://apigenie.pl/docs/reference/doc-components/reference-and-spec.md), [OpenAPI elements](https://apigenie.pl/docs/reference/doc-components/openapi.md), [Swagger 2.0 elements](https://apigenie.pl/docs/reference/doc-components/swagger.md), [AsyncAPI elements](https://apigenie.pl/docs/reference/doc-components/asyncapi.md), [Protobuf and gRPC elements](https://apigenie.pl/docs/reference/doc-components/protobuf.md), [GraphQL elements](https://apigenie.pl/docs/reference/doc-components/graphql.md), [Building blocks](https://apigenie.pl/docs/reference/doc-components/building-blocks.md), [Try it out](https://apigenie.pl/docs/reference/doc-components/try-it-out.md), [Theming](https://apigenie.pl/docs/reference/doc-components/theming.md), [Server-side rendering](https://apigenie.pl/docs/reference/doc-components/server-side-rendering.md).

`apigenie-generator docs` compiles OpenAPI, Swagger 2.0, AsyncAPI, GraphQL and Protobuf files into
a docs bundle (`apigenie-docs.json` and, per document and locale, the document or its
documentation model, with the git changelog and the example files) and an npm project whose
`build` script runs `apigenie-docs build` from this package
([apigenie-generator docs](/docs/reference/generator/docs)).

```sh
apigenie-generator docs openapi.yaml events.asyncapi.yaml --i18n pl=i18n-pl.json --changelog -o docs
cd docs && npm install && npm run build      # apigenie-docs build, into dist/
npm run build -- --base /docs/ --origin https://docs.example.com
```

## Usage

```text
apigenie-docs build [--bundle DIR] [--out DIR] [--base PATH] [--origin URL] [--clean] [--no-markdown] [--quiet]
```

| Option | Default | Description |
| --- | --- | --- |
| `--bundle DIR` | `.` | The bundle directory, holding `apigenie-docs.json`. |
| `--out DIR` | `dist` | The site directory. |
| `--base PATH` | `/` | The path the site is served at, such as `/docs/`. |
| `--origin URL` | | The site's origin, for the sitemap and canonical links. Without it, the sitemap lists paths. |
| `--clean` | | Empty the site directory first. |
| `--no-markdown` | | Write no Markdown copy of the pages, `llms.txt` or `llms-full.txt`. |
| `--quiet` | | Print nothing but errors. |
| `-h`, `--help` | | Print the usage. |

## Exit status

| Status | |
| --- | --- |
| `0` | The site was written, or `--help` printed the usage. |
| `1` | The build failed; the error is printed. |
| `2` | A usage error: no command, an unknown command or extra argument, an unknown option, an option without its value, or an `--origin` that is not a URL. The usage follows the error. |

## What it writes

- One prerendered page per document, locale and route:
  `<base><locale>/<document>/<route>/index.html`. The locale prefix is left out for the default
  locale unless the bundle sets `prefixDefaultLocale`. The document prefix is left out for a site
  of one document, so one document in one locale gives `/`, `/operation/getPet/`, and so on.
- An index page per locale when there are several documents, `sitemap.xml`, and, when the default
  locale has a prefix (`prefixDefaultLocale` in the bundle), an `index.html` at the root that
  redirects to `<base><locale>/`.
- The hydrate script and its chunks under `_apigenie/`, `oauth2-redirect.html`, and each
  document's JSON next to its pages.
- Next to each page its Markdown copy (`operation/getPet.md` beside `operation/getPet/`), for
  coding agents, linked from the page with `<link rel="alternate" type="text/markdown">`. The site
  root has `llms.txt`, which lists the copies of the default locale, and `llms-full.txt`, which
  holds them all.

Every page embeds its document (or documentation model) and the bundle's extras, so hydration
needs no WebAssembly module and no request. The pages get `<link rel="alternate" hreflang>` links
and a locale switcher, a Changelog page (`<apg-changelog>`) when the bundle has a changelog, and
the example files on the overview or on the GraphQL operation they are named after.

## As a library

The renderer is a library too: `@mykulyak/apigenie-docs/docs` (`buildDocs(options)`,
`readBundle(dir)`). The DOM-free part, `@mykulyak/apigenie-docs/bundle` (`parseManifest`,
`loadBundle`, `sitePages`, `changelogView`, …), reads a bundle anywhere. `<apg-api-reference>`
takes the extras on its own too: `changelog-url` (or the `changelog` property), `examples` and
`locales`.