Documentation style guide

We don’t have an official style guide yet, but the current OpenTelemetry documentation style is inspired by the following style guides:

• Google Developer Documentation Style Guide
• Kubernetes Style Guide

The following sections contain guidance that is specific to the OpenTelemetry project.

OpenTelemetry.io word list

A list of OpenTelemetry-specific terms and words to be used consistently across the site:

• OpenTelemetry and OTel
• Collector
• OTEP
• OpAMP

For a complete list of OpenTelemetry terms and their definition, see Glossary.

Make sure that proper nouns, such as other CNCF projects or third-party tools, are properly written and use the original capitalization. For example, write “PostgreSQL” instead of “postgre”. For a full list, check the .textlintrc.yml file.

Markdown

Site pages are written in the Markdown syntax supported by the Goldmark Markdown renderer. For the full list of supported Markdown extensions, see Goldmark.

You can also use the following Markdown extensions:

• Alerts
• Emojis: for the complete list of available emojis, see Emojis from the Hugo docs.

Alerts

You can write alerts using the following extended syntax:

• GitHub-flavored Markdown (GFM) alerts
• Obsidian callout syntax for custom alert titles

Here is an example of each:

> [!TIP]
>
> If you are writing new content, generally prefer using this blockquote alert
> syntax instead of the Docsy
> [alert shortcode](https://www.docsy.dev/docs/content/shortcodes/#alert).

> [!WARNING] :warning: Blank line required!
>
> This site uses the [Prettier] formatter, and it requires an empty line
> separating the alert tag/title from the alert body.

These render as:

For details about the blockquote alert syntax, see Alerts from the Docsy docs.

Link references

When using Markdown reference links, prefer the collapsed form [text][] over the shortcut form [text]. While both are valid CommonMark, the shortcut form is not consistently recognized by all Markdown tools. In particular, if you write [example] and forget the definition, the markdownlint linter won’t warn you¹ – the text silently renders as literal [example] instead of a link. With the collapsed form [example][], the linter catches the missing definition immediately.

This is enforced by the no-shortcut-ref-link custom rule. Run npm run fix:markdown to convert shortcut references automatically.

Markdown checks

To enforce standards and consistency for Markdown files, all files should follow certain rules, enforced by markdownlint. For a full list, check the .markdownlint.yaml and .markdownlint-cli2.yaml files.

When legitimate exceptions to a rule exists, use markdownlint-disable directive to suppress the rule warnings. For details, see the markdownlint documentation.

We also enforce Markdown file format and strip files of trailing whitespace. This precludes the line break syntax of 2+ spaces; use <br> instead or reformat your text.

Spell checking

Use CSpell to make sure that all your text is spelled correctly.

If cspell reports an “Unknown word”, check whether you wrote the word correctly. If so, add the word to one of these locations:

• A page-local cSpell:ignore list in the page front matter. For details, see below.
• Your locale-specific word list file
• The general all-words.txt word list

Page-local cSpell:ignore list

If the unknown word appears only on a single or a few pages, add it to a page-local cSpell:ignore list in the page front matter:

---
title: PageTitle
cSpell:ignore: <word>
---

For non-Markdown files, add cSpell:ignore <word> in a comment line appropriate for the file. For example, in a registry entry YAML file, it might look like this:

# cSpell:ignore <word>
title: registryEntryTitle

Word list files

If the unknown word appears in multiple pages or is a technical term, add it to your locale-specific word list file. Word list files are located in the .cspell/ directory.

If the word is spelled correctly in all locales, such as opamp, add it to the all-words.txt file.

File format

We use Prettier to enforce file formatting. Invoke it using:

• npm run fix:format to format all files
• npm run fix:format:diff to format only the files that have changed since the last commit
• npm run fix:format:staged to format only the files that are staged for the next commit

File names

All file names should be in kebab case.

Fixing validation issues

To learn how to fix validation issues, see Pull request checks.