This is the main repository for the documentation of the Stackable platform. Have a look at the live version and the current nightly live version.
The documentation is built with Antora.
This repository hosts the Antora playbook file as well as platform documentation.
Other Stackable repos contain docs directories which are pulled in by this repo.
-
The
antora.ymlfile defines the mainhomeComponent. -
The various
*-playbook.ymlfiles are Antora playbook files used to build the docs, either locally or for production. The playbooks link to all the other repositories that contain content. -
The
modulesdirectory contains the platform level documentation content.
Dependencies: make, npm.
To build the site, install dependencies and run make:
$ npm ci $ make
|
Note
|
Antora caches the external content repos in the cache directory (configured to be ./cache).
It will not automatically update those.
Use the --fetch flag (make ANTORAFLAGS=--fetch) to update all sources, or use make clean to delete the cache and build directory.
|
The documentation is deployed by Netlify on a regular basis or when something is pushed to the main branch.
To trigger an out of band deployment, use the Build and deploy production site GitHub action (internal contributors only).
Regular (nightly) deployments are run to pick up changes in the operator repositories. These repositories are not watched by Netlify and thus any changes to the documentation there would be ignored.
Netlify is configured with the netlify.toml file inside of the documentation repo.
In there, the command make netlify-build is configured as the build command.
Further documentation of the build process can then be found in the Makefile.
The build process creates a static site in build/site which is then published (as it is configured in the netlify.toml).
During development, it can be helpful to use a playbook local-antora-playbook.yml which uses content from the local directory instead of the remote git repository. The playbook used by the Makefile can be overridden using the PLAYBOOK variable (run make PLAYBOOK=my-local-playbook.yml).
content: sources: - url: ./ branches: HEAD
The design & layout lives in the ui/ directory of this repository.
To see UI changes rendered with real content, rebuild with make build-truly-local.
-
The CRD reference on the Stackable Hub.
-
The Stackable contributor’s guide containing more info on how to contribute to the documentation.