apigenie-docs build

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

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

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.