= Stackable Documentation :base-repo: https://github.com/stackabletech

This is the main repository for the documentation of the Stackable platform. Have a look at the https://docs.stackable.tech/[live version] and the current https://docs.stackable.tech/home/nightly/[nightly live version].

The documentation is built with https://antora.org[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.

== Repository structure

• The link:antora.yml[antora.yml] file defines the main home https://docs.antora.org/antora/latest/component-version/#docs-component[Component].
• The various *-playbook.yml files are https://docs.antora.org/antora/latest/playbook/[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 modules directory contains the platform level documentation content.

== Building locally

Dependencies: make, npm.

To build the site, pull submodules, install dependencies and run make:

[source,console]

$ git submodule update --init $ 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.

== Production deployment

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 configuration

Netlify is configured with the link:netlify.toml[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 link:Makefile[Makefile].

The build process creates a static site in build/site which is then published (as it is configured in the netlify.toml).

== Development

=== Generating the documentation

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

[source,yaml]

content: sources:

• url: ./ branches: HEAD

NOTE: Antora does not recognize git submodules as git repositories

The design & layout comes from our https://github.com/stackabletech/documentation-ui[UI repository].

LIVERELOAD=true gulp may be used to recreate the built documentation after each edit.

== More useful links

• The https://github.com/stackabletech/documentation-ui[documentation-ui] repository.
• The https://github.com/stackabletech/crddocs[crddocs] repository from which the https://crds.stackable.tech/[CRD reference] is generated.
• The Stackable https://docs.stackable.tech/home/stable/contributor/[contributor's guide] containing more info on how to contribute to the documentation.