Documentation Editing and Contribution
Writing Documentation
We welcome contributions to documentation!
Running the site
If you clone the repository and run make site-server from the build directory, this will run the live hugo server,
running as a showing the next version’s content and upcoming publishedDate'd content as well. This is likely to be
the next releases’ version of the website.
To show the current website’s view, run it as make site-server ENV=RELEASE_VERSION=1.10.0 ARGS=
Platform
This site and documentation is built with a combination of Hugo, static site generator, with the Docsy theme for open source documentation.
Documentation for upcoming features
Since we may want to update the existing documentation for a given release, when writing documentation, you will likely want to make sure it doesn’t get published until the next release.
There are two approaches for hiding documentation for upcoming features, such that it only gets published when the version is incremented on the release:
At the Page Level
Use publishDate and expiryDate in Hugo Front Matter to control
when the page is displayed (or hidden). You can look at the Release Calendar
to align it with the next release
candidate release date - or whichever release is most relevant.
Within a Page
We have a feature shortcode that can be used to show, or hide sections of pages based on the current semantic version
(set in config.toml, and overwritable by env variable).
For example, to show a section only from 0.8.0 forwards:
{{% feature publishVersion="0.8.0" %}}
This is my special content that should only display >= 0.8.0
{{% /feature %}}
or to hide a section from 0.8.0 onward:
{{% feature expiryVersion="0.8.0" %}}
This is my special content that will be hidden >= 0.8.0
{{% /feature %}}
Warning
Due to this hugo bug headers wrapped in this shortcode will not be displayed in the Table of Contents. So we will need to actively remove thefeature shortcode once
the release versions have been passed for new content, for content that is affected.
Regenerate Diagrams
To regenerate the PlantUML or Dot diagrams,
delete the .png version of the file in question from /site/static/diagrams/, and run make site-images.
Feedback
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.