Stackable Documentation

This is the main repository for the documentation of the Stackable platform. Have a look at the 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.

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

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

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

content:
  sources:
  - url: ./
    branches: HEAD

Note	Antora does not recognize git submodules as git repositories

The design & layout comes from our UI repository.

LIVERELOAD=true gulp may be used to recreate the built documentation after each edit. The 'live reload' feature does not work over gitpod currently due to schickling/gulp-webserver#126

Remote IDE

A remote vscode instance can be used via https://gitpod.io/#/github.com/stackabletech/documentation