Concept Topic Structure
Describes the contents of a concept topic
6 minute read
This page gives writing style guidelines for the Gardener documentation. For formatting guidelines, see the Formatting Guide.
These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a Pull Request.
The following table summarizes the types of documentation and their mapping to the UA taxonomy. Every topic you create will fall into one of these categories.
Gardener Content Type | Definition | Example | Content | Comparable UA Content Type |
---|---|---|---|---|
Concept | Introduce a functionality or concept; covers background information. | Services | Overview, Relevant headings | Concept |
Reference | Provide a reference, for example, list all command line options of gardenctl and what they are used for. | Overview of kubectl | Relevant headings | Reference |
Task | A step-by-step description that allows users to complete a specific task. | Upgrading kubeadm clusters | Overview, Prerequisites, Steps, Result | Complex Task |
Trail | Collection of all other content types to cover a big topic. | Custom Networking | None | Maps |
Tutorial | A combination of many tasks that allows users to complete an example task with the goal to learn the details of a given feature. | Deploying Cassandra with a StatefulSet | Overview, Prerequisites, Tasks, Result | Tutorial |
See the Contributors Guide for more details on how to produce and contribute documentation.
When creating a new documentation topic or folder, it is important to adhere to a consistent and clear naming convention. This ensures that topics are easily identifiable and helps maintain a well-structured documentation repository. The title of your newly created content should be in dash-case (also known as kebab-case). This means each word in the file or folder name should be separated by a hyphen (-), and all letters should be in lowercase.
By default, this will also be the title of your topic in the website.
For example, a new-topic-title.md
filename will generate the topic’s title as “New Topic Title”. You can customize the title by adding front matter to the top of your Markdown file.
If you would like to have a newly added folder appear in the website navigation, you need to add an _index.md
file to it. As folders are hidden by default, this file will hold its title, description, weight, and other possible properties. For more information, see the Front Matter section.
When creating a topic, you will need to follow a certain structure. A topic generally comprises of, in order:
.md
files in Gardener) - Additional information about the topicYou can use the provided content description files as a template for your own topics.
Front matter is metadata applied at the head of each content Markdown file. It is used to instruct the static site generator build process. The format is YAML and it must be enclosed in leading and trailing comment dashes (---
).
Sample codeblock:
---
title: Getting Started
description: Guides to get you accustomed with Gardener
weight: 10
aliases: ["/docs/old-getting-started-url"]
---
<topic-content>
There are a number of predefined front matter properties, but not all of them are considered by the layouts developed for the website. The most essential ones to consider are:
title
the content title that will be used as page title and in navigation structures. If not set, the title of the topic will be file name in uppercase (e.g., new-topic-title.md
will be rendered as “New Topic Title”).
description
describes the content. For some content types such as documentation guides, it may be rendered in the UI.
weight
a positive integer number that controls the ordering of the content in navigation structures. The lower it is, the higher the topic will be on the page. Topics with no set weight are sorted in alphabetical order, with any weighted topics appearing above them.
url
if specified, it will override the default url constructed from the file path to the content. Make sure the url you specify is consistent and meaningful. Prefer short paths. Do not provide redundant URLs!
persona
specifies the type of user the topic is aimed towards. Use only a single persona per topic.
persona: Users / Operators / Developers
aliases
is an array of strings that contain the old paths to the topic. Useful in case you need to rename or change the location of a topic, but want to keep any existing bookmarks.
While this section will be automatically generated if your topic has a title header, adding more detailed information helps other users, developers, and technical writers better sort, classify and understand the topic.
By using a metadata section you can also skip adding a title header or overwrite it in the navigation section.
If you want to add a note, tip or a warning to your topic, use the templates provides in the Shortcodes documentation.
If you want to add an image to your topic, it is recommended to follow the guidelines outlined in the Images documentation.
Describes the contents of a concept topic
Describes the contents of a reference topic
Describes the contents of a task topic
Was this page helpful?