APPUiO Cloud :: Documentation for System Engineers

This repository contains all the content hosted at https://kb.vshn.ch/appuio-cloud/.

The content is written in AsciiDoc and rendered using Antora.

Tip	Writing AsciiDoc is best done using Visual Studio Code with the AsciiDoc addon. For a reference what you can do with AsciiDoc, have a look at AsciiDoc Writer’s Guide. Antora is capable of doing many great things with documentation. See the Antora docs to gain insights into the tooling.

Documentation structure

The documentation structure is inspired by the Divio’s documentation structure:

Tutorials (Learning-oriented)

A lesson which teaches you something. Location: docs/modules/ROOT/pages/tutorials.

How-to guides (Problem-oriented)

Step-by-step guides to achieve a goal. Location: docs/modules/ROOT/pages/how-tos.

Technical reference (Information-oriented)

Description about the inner ongoings. Location: docs/modules/ROOT/pages/tutorials.

Explanation (Understanding-oriented)

Explains the background. Location: docs/modules/ROOT/pages/explanations.

Contributing

Create a new branch to make the changes. After you’re satisfied with the changes open a Pull Request against the master branch.

Previewing Changes

To preview your changes locally, make sure you have Docker or Podman installed.

Just type make preview and open your browser at http://localhost:2020. This even provides support for live reload when working on the content. See this documentation for more information about it.

Adding a New Page

1. Create new AsciiDoc (.adoc) file in the best matching folder according to the described structure under docs/modules/ROOT/pages/.

2. Add the file to the navigation under docs/modules/ROOT/partials/

For removing pages just do the opposite: Remove the file and remove the entry in the navigation.

Deployment

This repository only holds Antora content, no plumbing and tooling (aka the Antora playbook.yml and Dockerfile) to build and deploy it. All pushes to the master branch trigger a GitHub action (.github/worflows/triggerci.yml) which in turn triggers the GitLab CI job to build and deploy the content using Antora.