# opentelemetry.io is the docs repository behind the OpenTelemetry site

> This is not the OpenTelemetry code, it is the place the OpenTelemetry code is written down. The repository holds the website, the project documentation and the blog, built with Hugo and hosted on Netlify, and it is a surprisingly good example of a documentation project: monthly content releases, a four level review structure, and a linting stack that checks prose, links, spelling and translation formatting separately.

**open-telemetry/opentelemetry.io** — The OpenTelemetry website and documentation

- Repository: https://github.com/open-telemetry/opentelemetry.io
- Website: https://opentelemetry.io
- Stars: 994 · Forks: 1,986
- Language: JavaScript
- License: CC-BY-4.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/open-telemetry-opentelemetry-io

## A documentation repository with a public roadmap of contributors

The repository description is short, this is the source repository for the OpenTelemetry website, project documentation and blog, built with Hugo and hosted on Netlify. The primary language is recorded as JavaScript, which tells you the tooling layer is Node based even though the site generator is Go, and the site is a Hugo project with content in Markdown. The README is mostly a map of the project's process rather than a description of the software, and three things in it are worth reading before you contribute. The contributor's guide is pointed at as covering how to contribute fixes and new content, including a style guide and information about the review process. There is separate guidance for submitting a blog post. And there is a security policy, with the instruction to read it before opening an issue if you find a security problem. A registry section, which would explain how to add a project to the OpenTelemetry ecosystem registry, is present but commented out in the README, which suggests the registry workflow is handled elsewhere at the moment.

## The build is Hugo, and the built site is committed to a branch

The build pipeline has an unusual and rather clever shape. The Makefile in the root defines an `OTEL_GEN_REPO` variable, a path to a sibling git repository, and the `public` target either symlinks that repository into `public/` or, when it is not running in CI, initialises an empty git repository there. The comment explains the reason, it is for the purpose of tracking build changes. The `clean` target removes the temporary, public and resource directories:

```bash
rm -rf tmp public/* resources
```

And the npm scripts do the rest, with `_build` running Hugo in development mode with drafts and future posts enabled and a base URL taken from the `DEPLOY_PRIME_URL` environment variable, and `_commit:public` checking out the short hash of the main branch, changing into the public directory and committing the whole site as `Site at $HASH`. So a release is a commit of a generated site into a separate repository, which is how a Hugo site on Netlify gets a preview of the exact tree that will be published.

## Prose is checked by a stack of separate tools

The npm scripts show how seriously documentation is treated here, and the pattern is that each class of error has its own tool. Formatting is Prettier, and there is a separate check for the Japanese, Ukrainian and Chinese content, `_check:format:nowrap`, which uses the `prose-wrap preserve` option, so translated files are allowed to keep their own line breaking. Links are checked with lychee, through a generated config and a report script:

```bash
node scripts/lychee/check-report/cli.mjs *.md
```

Text is checked with textlint over the content, the data and the top level Markdown files. Spelling is handled by cspell, with a script that finds the Markdown files that are not old blog posts and normalises the cspell front matter, and a warnings skip list for words that are allowed to fail. There are separate markdownlint configurations for the main content and for the specifications, and a `prh` directory for Japanese writing rules, and a code excerpt tool for the English content. The `link-cache.jsonc` file at the root and the `.warnings-skip-list.txt` both suggest the same lesson, that a documentation project at this scale needs to remember which checks have already been made.

## Translation is treated as a first class content type

The tree has an `i18n/` directory and a `content-modules/` directory, and the scripts treat translations differently from English rather than as a copy of it. The Japanese, Ukrainian and Chinese content gets its own formatting check because prose wrapping rules differ by language, the Japanese content has a `prh/` directory for writing rules, and the site carries `.python-version` and a collector sync script that requires the uv tool, with a dedicated check that fails early with an install hint if uv is missing. The `textlint` invocation covers the content, the data and the top level Markdown, so translated pages are linted by the same text rules as the English ones. The net effect is that a translation is not a mechanical copy that lands and is forgotten, it is a maintained artefact with its own checks, which is why the project publishes a contributor's guide in more than one language and asks contributors to fix the translations they read.

## Four review roles, and a meeting every two weeks

The README documents the community structure in detail, which is unusual for a documentation repository and is the most transferable part of it. There are maintainers, with six named and their affiliations listed, three of them from Grafana Labs, one from the CNCF, one from Bronto and one without a listed affiliation. There are approvers, one named, from VictoriaMetrics. There are triagers, four named, from companies including Grafana Labs and DrDroid. And there is an emeritus group, thirteen names with the role each held, maintainer, approver or triager, including people who were around the original OpenTelemetry work. The governance is in the separate community repository, with guides for each role. The working rhythm is documented too, the OTel Communications SIG meets every two weeks on Tuesday at 9:00 AM Pacific, with the Zoom link in the community calendar, notes in a public Google document, and the `#otel-comms` channel on Slack for anyone who cannot reach the document.

## Monthly content releases, and a site that is measured

The release list shows three content releases in a row, 2026.09 on 2026-10-04, 2026.08 on 2026-09-01 and 2026.07 on 2026-08-03, which is a monthly cadence with the date stamped in the version. The last push to the repository was on 2026-10-20, so the site is worked on continuously and published on a schedule rather than in bursts, which is the right shape for documentation that people follow links into. The repository also links an analytics dashboard for the site itself, hosted on Looker Studio, and the README is candid that website analytics exist, which is a small piece of honesty that most projects would leave out of a readme. The combination of a monthly release train, a named set of maintainers and approvers and a documented meeting schedule is what makes this a good model for a documentation project run the way an open source project usually is.

## Two licences, and where to start if you want to help

The licences section is the shortest and most concrete part of the readme. The documentation is under CC-BY-4.0, in the `LICENSE` file, and the code in the repository is under Apache-2.0, in a separate `LICENSE-CODE` file. That split is the right one for a documentation site, since it lets anyone reuse a page with attribution while keeping the tooling permissive, and it is worth checking before you copy a page into your own project. The rest of the tree supports the process rather than the content. There is a `Makefile`, an npm workspace for the community data generator, `netlify.toml` and a `netlify/` directory for the hosting configuration, a dev container and a Gitpod configuration for a one click development environment, and agent instruction files in `AGENTS.md` and `CLAUDE.md` alongside an `.agents/` and a `.claude/` directory. For a newcomer the readme is unusually direct about the value of the work, since the website and the documentation is the entry point for people learning the project, so an unclear page is a real gap rather than a cosmetic one.

## Conclusion

opentelemetry.io suits a maintainer who wants to fix a page in a project with a large audience, since the contribution guide, the review roles and the local build are all documented, and it suits a team looking for a model of how a multi language documentation site is kept honest. It is a poor fit if you want to change the telemetry itself, since no code in this repository ships a collector or an SDK. It is also a poor fit if you want a quick edit, because the linting stack, the translation mirrors and the review roles all make the process heavier than a README. Before you open a pull request, check three things: the contributor's guide, which carries the style guide and the review process, the release cadence, since content releases are monthly and the last one was 2026.09, and the licence split, since the documentation is CC-BY-4.0 and the code in the repository is Apache-2.0.

## FAQ

### What is the opentelemetry.io repository?

The source repository for the OpenTelemetry website, project documentation and blog. The site is built with Hugo and hosted on Netlify, and the repository also carries the tooling for linting, translating and publishing the content.

### How do I build the OpenTelemetry site locally?

The README points at the development setup page in the docs for the local build. The Makefile supports it with a public target that symlinks an external git repository or initialises an empty one, so the built site can be committed and tracked, and the npm scripts run Hugo in development mode with drafts and future posts enabled.

### What checks run on the OpenTelemetry documentation?

Prettier for formatting with a separate pass for the Japanese, Ukrainian and Chinese content, lychee for link checking, textlint for prose, cspell for spelling with a front matter normalisation script, markdownlint with separate configurations for the main content and the specifications, and a prh directory for Japanese writing rules.

### How are contributions to the OpenTelemetry docs reviewed?

The repository lists maintainers, approvers, triagers and emeritus members with their affiliations, and points at guides for each role in the OpenTelemetry community repository. The OTel Communications SIG meets every two weeks on Tuesday at 9:00 AM Pacific, with notes in a public document and discussion in the #otel-comms Slack channel.

### What licence covers the OpenTelemetry website content?

Two licences, with the documentation under CC-BY-4.0 in the LICENSE file and the code in the repository under Apache-2.0 in a separate LICENSE-CODE file. The content releases are monthly, with 2026.09 published on 2026-10-04.

## Sources

- [License: CC-BY-4.0](https://github.com/open-telemetry/opentelemetry.io/blob/main/LICENSE)
- [open-telemetry/opentelemetry.io on GitHub](https://github.com/open-telemetry/opentelemetry.io)
- [Project website](https://opentelemetry.io)
- [README](https://github.com/open-telemetry/opentelemetry.io/blob/main/README.md)
- [Releases](https://github.com/open-telemetry/opentelemetry.io/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/open-telemetry-opentelemetry-io