Writing documentation
New documentation is always welcome!
Start by cloning the documentation repository and installing the necessary requirements:
git clone --recurse-submodules \
https://gitlab.com/cki-project/documentation \
documentation
cd documentation
make setup
This requires Hugo to be installed via the system package manager. Instead,
it is also possible to execute all of the commands in the shell of a container
with everything preinstalled via make podman
.
Add new documentation as markdown files inside the appropriate directory
under content/
. Every file should end in .md
. The repositories use Hugo
with the Docsy theme to build the site.
Documentation can be previewed by running make serve
. A local web server will
start and automatically refresh the preview each time a change is saved.
Available tests can be executed by running make test
.
To submit changes, fork the repository, add the fork as a remote to the checkout and commit the changes. Push them to a new branch in the fork, and start a merge request against the parent.
Internal repository
The CKI documentation is open by default and maintained via the public repository. Additionally, an internal repository exists to be able to provide further confidential information.
The contents of these two repositories are used to generate two different versions of the documentation:
- the public documentation, solely based on information from the public repository
- the internal documentation, based on information from the public repository, supplemented by confidential details about internal infrastructure from the internal documentation repository
The CKI deployment bot is configured to redeploy the internal documentation when changes to the public repository are merged.
To contribute to the internal repository, install some additional dependencies, clone the internal documentation repository next to the public repository, and link both checkouts via
sudo dnf install inotify-tools stow
git clone --recurse-submodules \
https://internal/documentation/repository.git \
internal-documentation
cd internal-documentation
mkdir stow
ln -s ../../documentation stow/public
./build.sh && cd build
make setup
The build.sh
script uses stow to interleave files from the public and
internal repositories, with files from the internal repository taking
precedence. This allows the internal repository to add or overwrite
files from the public repository.
Run make serve
in the build
directory to start a local web server that
serves the merged documentation.
Adding confidential information
With Hugo, content is organized into page bundles.
As an example, consider the following structure in the public repository:
documentation/content/
\- _index.md
\- page1.md
\- page2/
\- index.md
This will generate three pages: an index page for the top-level _index.md
,
and two content pages for page1.md
and page2/index.md
.
To include confidential content from additional Markdown files supplied via the internal repository:
-
In the public repository, move content Markdown files in branch bundles (directories with a
_index.md
file) into separate leaf bundles. In the example, this means movingpage1.md
into a separate directory:documentation/content/ \- _index.md \- page1/ \- index.md \- page2/ \- index.md
-
In the internal repository, add the confidential content as a separate Markdown file in the appropriate page bundle:
internal-documentation/content/ \- page1/ \- confidential-section.md
This is what
content/page1/confidential-section.md
in the internal repository could look like:--- --- <!-- markdownlint-disable first-line-heading --> ## Confidential section Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. ...
-
Reference the file via the
include
shortcode incontent/page1/index.md
in the public repository:... {{% include "confidential-section.md" %}} ...
When the public documentation is rendered, the missing include is ignored gracefully.