The Grafana Labs Docs team makes intentional decisions about how to organize and structure product documentation. The topic levels discussed on this page reflect common user goals. For example, a first-time Grafana user needs to understand the basic concepts before installing the product.
Before you begin contributing to documentation, it is important to understand the structure of the content.
User goals and documentation structure
When writing documentation, focus on what your user’s goals are. For more information, refer to Focus on user goals.
Use the structure of your documentation to reflect the user’s goals. Think about what your users want to do, what they need to know, and how they can accomplish the tasks.
This approach applies not only to content on a page but also to how you organize a set of documentation, whether it’s for a product or a feature.
With well-structured content, you can find what you need quickly and easily. Topics flow in a logical progression.
Structure of published content
Generally, documentation structure determines how content is:
- Combined (or not combined) with other, related content
A standardized content structure that spans sets of documentation provides a consistent user experience. Information flows from a higher (less specific) level to a lower (more specific) level. For example, a new Grafana user wants to learn conceptual information first, so Introduction comes before Installation.
Use the topics you need
Depending on your product design and maturity, you may not need every topic:
- If a topic does not apply to your project, you don’t need to use it.
- For Grafana OSS for example, you might use all of the headings.
- For Grafana Enterprise Traces for example, you might only use a subset of topics.
Some topics are optional and are usually found in specific contexts. For example, the Create, Manage, and Monitor topics are used in Grafana OnCall, but are not used in Grafana Tempo.
You can use the following high-level topics to group content. When writing new content, consider where it should appear given this content structure. For example, a conceptual page explaining metrics would go under the Introduction topic.
|Introduction to Grafana
|Conceptual, fundamental, or architectural information.
|Get started with Tempo
|Opinionated walk-throughs and tutorials.
|Set up Grafana
|System requirements, and subsections titled Set up, Configure, Upgrade, or Migrate.
|Configure Grafana Agent
|Configure can be its own section directory if the number of pages warrants it. Making this determination is not an exact science; use your best judgement.
|Create a Grafana managed alert rule
|Specific to Grafana Ops products (Alerting, OnCall, Incident, SLOs). The word alert may be changed, depending upon the product. If used with Grafana SLO, this then topic would be Create SLO. Do not use with backend database products, such as Tempo and Loki. Use Alerts instead, and refer to an operational product for details.
|Manage and monitor SLOs
|Specific to Grafana Ops products (Alerting, OnCall, Incident, SLOs). Do not use with backend database products, such as Tempo and Loki. Use Alert instead, and refer to an operational product for details.
|Integrate (with) [product] or Send data
|Connect your data to Grafana Cloud
|How to set up data integrations, product integrations, data sources, clients, plugins, and more.
|Query languages, query tools, and examples.
|Dashboard concepts and procedures. Link to the definitive source of dashboard documentation, rather than duplicating the information here.
|This topic level is used for pages that discuss alerting features, like Grafana Loki’s alerting rules. It provides a place for alerting content that is not specific to the Grafana Operations products.
|Manage users and teams with Grafana OnCall
|Information about managing a Grafana Labs product. For example, content in this topic helps you view, edit, and iterate on the Grafana product you installed.
|Information about using tools to monitor a Grafana Labs product.
|HTTP API reference
|APIs, configuration references, SDKs, and more. Material that is usually not procedural.
Table of contents levels
The table of contents consists of the following section levels.
Top-level: A table of contents top-level represents groups of features and functions of a product. The first step in contributing to the docs is to identify which top-level entity you will be contributing to.
NoteDo not add a top-level entity to the table of contents. If you are not sure where your documentation belongs, contact the technical documentation team.
Parent: Each top-level entity has one or more parents, which are groups of related feature content. Parent topics assist users in navigating to child topics.
Child: This level of the information architecture includes includes concepts, tasks, or reference topics.
Parent directory structure
Within the top-level directory, there is a parent directory.
The image below shows how the repository’s
user-management parent directory is structured.
- There is an
_index.mdfile in the parent directory that serves as a landing page for the child topics. In most cases,
_index.mdcontains conceptual content. For information about the types of conceptual content that you can add to the
_index.mdfile, refer to Concepts.
- There are also four task topics in the parent directory, each with a directory and
Note: If a directory contains multiple pages or subdirectories, it is a branch bundle, and it must include an
_index.mdfile. A directory containing only one page is a leaf bundle, and the content filename must be
Pages and page bundles
Each web page generated by Hugo comes from one of three source files:
page/_index.md: a Hugo branch bundle
page/index.md: a Hugo leaf bundle
page.md: a Hugo page
Although each of the preceding examples results in the same URL (
/page/), Hugo works with each source file differently.
Branch bundles (
page/_index.md) are required to produce page hierarchies.
/page/subpage/ URL to generated, there must first be a
page/_index.md branch bundle source file.
Leaf bundles (
page/index.md) are required to conveniently and consistently bundle page assets.
To refer to a style sheet
page/style.css with the link
./style.css, the link must be in a
page/index.md leaf bundle source file.
Leaf bundles (
page/index.md) are also required to mount content from one part of the site to another using Hugo mounts.
Hugo mounts use a virtual filesystem before site generation, and only directories can be mounted.
To mount the page
/other/page/, there must first be a
page/index.md leaf bundle source file.
If you don’t know whether you need to mount a leaf bundle, you probably don’t and default to using pages.
page.md) are any source files that are not leaf or branch bundles.
It is convenient to use pages when none of the behaviors of leaf or branch bundles are required, as it can be easier to distinguish two source files in some text editors or IDEs.
For more information about branch bundles and leaf bundles, refer to Page bundles.