Menu
Open source

Documentation structure

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:

  • Titled
  • Grouped
  • 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.

Topic list

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.

TopicExample linkContents
IntroductionIntroduction to GrafanaConceptual, fundamental, or architectural information.
Get startedGet started with TempoOpinionated walk-throughs and tutorials.
Set upSet up GrafanaSystem requirements, and subsections titled Set up, Configure, Upgrade, or Migrate.
ConfigureConfigure Grafana AgentConfigure 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 alertsCreate a Grafana managed alert ruleSpecific 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 alertsManage and monitor SLOsSpecific 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 dataConnect your data to Grafana CloudHow to set up data integrations, product integrations, data sources, clients, plugins, and more.
Query dataTraceQLQuery languages, query tools, and examples.
Visualize dataDashboardsDashboard concepts and procedures. Link to the definitive source of dashboard documentation, rather than duplicating the information here.
AlertAlerting rulesThis 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 [product]Manage users and teams with Grafana OnCallInformation about managing a Grafana Labs product. For example, content in this topic helps you view, edit, and iterate on the Grafana product you installed.
Monitor [product]Monitor MimirInformation about using tools to monitor a Grafana Labs product.
ReferencesHTTP API referenceAPIs, 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.

Grafana table of contents

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.

Note

Do 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.md file in the parent directory that serves as a landing page for the child topics. In most cases, _index.md contains conceptual content. For information about the types of conceptual content that you can add to the _index.md file, refer to Concepts.
  • There are also four task topics in the parent directory, each with a directory and index.md file.

For more information about how to write concepts, refer to Concepts. For more information about how to write tasks, refer to Tasks.

Parent directory structure

Note: If a directory contains multiple pages or subdirectories, it is a branch bundle, and it must include an _index.md file. A directory containing only one page is a leaf bundle, and the content filename must be index.md.

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. For the /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 /page/ to /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.

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.