Repository files navigation

KubeStack+ docs are built usingMkDocs which is based on Python.

This repository has GitHub action workflow which checks the quality of the documentation and builds the Dockerfile image on Pull Requests. On a push to the main branch, it will create a GitHub release and push the built Dockerfile image to an image repository.

There are at least three options to get fast continuous feedback during local development:

1. Build and run the docs using the Dockerfile image
2. Run the commands locally
3. Use Tilt

Checkout remote module:

git submodule update --init --recursive --remote

Build Dockerfile test image:

docker build. -ttest

Run test container:

docker run -p 8080:8080test

Then access the docs onlocalhost:8080/kubestackplus.

Usevirtualenvwrapper to set up Python virtual environments.

InstallPython 3.

Install mkdocs-material and mermaid plugin:

pip3 install mkdocs-material mkdocs-mermaid2-plugin

Install mkdocs-include-markdown-plugin (if not installed by default and gives an error):

pip install mkdocs-include-markdown-plugin

Finally, serve the docs using the built-in web server which is based on Python http server - note that the production build will usenginx instead:

mkdocs serve

or

python3 -m mkdocs serve

Markdown linting:

brew install markdownlint-climarkdownlint -c .markdownlint.yaml content

Spell checking:

brew install valevale content

InstallTilt, then run:

tilt up

Filesmain.html and404.html are served fromtheme_common rather than override since they are to be consistent throughout. If anything changes they can be served viatheme_override.

To execute the prepare theme command after setup you need to add theprepare_theme.sh or copy and paste bash file using sudo command file to your root directory and then run the following command:

chmod +x prepare_theme.sh