Skip to content

Latest commit

 

History

History
125 lines (81 loc) · 4.24 KB

WRITING-DOCUMENTATION.md

File metadata and controls

125 lines (81 loc) · 4.24 KB
Raw

Writing documentation

After starting the site locally, navigate to http://localhost:8080/docs/. This is where you can view your work as you write your documentation.

Versions

The code uses trunk based development where master is the trunk branch.

A single sourced folder in app/_src is used for each version of Kuma. We use a Jekyll plugin to dynamically generate pages from a single source file.

For the future non-patch versions of Kuma, changes can be made to the docs_nav_kuma_dev.yml file.

Writing docs for a new feature

If you are writing docs for a new feature you'll want to add it in the src folder.

Since content is single sourced, you must use conditional rendering to ensure that the new feature content only displays for that version. For example:

{% if_version eq:2.1.x %}
This will only show for version 2.1.x
{% endif_version %}

Diagrams

The team is moving diagrams to Google slides. Instructions are in the first slide. Ask a maintainer to get write access.

Mermaid.js diagrams

You can use Mermaid.js diagrams in our documentation. It can be used with the following syntax:

{% mermaid %}
{% endmermaid %}

For example, if you wanted to make a flowchart, you can use the following syntax:

{% mermaid %}
flowchart TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]
{% endmermaid %}

This flowchart would render like the following in the docs:

Mermaid flowchart example

You can use https://mermaid.live/edit to generate diagrams and see the rendered output before adding it to docs.

Note: Currently, Mermaid isn't supported in navtabs.

Cutting a new release

To cut the dev release, create a duplicate of the docs_nav_kuma_dev.yml file and then rename one of the files to "docs_nav_kuma_[version].yml". Update the release: dev metadata in the new release file with the release version.

Update the app/_data/versions.yml file with metadata specific to this release, for example: actual patches released, helm versions.

Set up local builds with yarn

Before start, make sure that installed Ruby version is the same as in the .ruby-version file.

  1. Install:

    make install

  2. Build:

    make build

  3. Serve:

    make serve

You will need to run make build after making any changes to the content. Automatic rebuilding will be added in November 2022.

Set up local builds with Netlify

If you get errors on the Netlify server, it can help to set up a local Netlify environment.

It has happened, however, that make build and the local Netlify build succeed, and the build still fails upstream. At which point … sometimes the logs can help, but not always.

WARNING: when you run a local Netlify build it modifies your local netlify.toml. Make sure to revert/discard the changes before you push your local.

Add generated docs from protobufs

If you create a new policy resource for Kuma, you should rebuild the generated policy reference documentation.

Markdown features

For more information about the Markdown features and formatting that is supported, see the following:

Vale

Vale is the tool used for linting the Kuma docs. The Github action only checks changed lines in your PR.

You can install Vale and run it locally from the repository root with:

vale sync # only necessary once in order to download the styles
vale <any files changed in your PR or ones you want to check>

Spurious warnings

If Vale warns or errors incorrectly, the usual fix is to add the word or phrase to the vocab list in .github/styles/Vocab.