cloudparts

Docsy

A free Hugo theme for technical documentation: Markdown in a Git repository becomes a docs site with sidebar navigation, search, translations, a blog and Markdown copies for AI agents. Kubernetes, etcd and OpenTelemetry use it.

Linux Foundation project
What it is
Documentation sites
Type
Open source
Made by
Docsy project (LF Projects, started at Google)
Foundation
The Linux Foundation, joined August 2026. A series of LF Projects, LLC, contributed by Google
License
Apache 2.0
Facts checked
28 October 2026
Website Source code

What it is

Docsy is a theme for Hugo, the Go static site generator, not a hosted service. You write pages as Markdown under content/, import the theme as a Hugo module (or from npm as @docsy/theme, or as a Git submodule), and hugo renders a static site you can put on any web host. The theme supplies what a documentation set needs on top of Hugo: a top bar and a left sidebar built from the folder tree, a page table of contents, breadcrumbs, “edit this page” and “create issue” links to the repository, a blog section, tags, a print view of a whole section, light and dark modes, right-to-left languages, and shortcodes for tabs, alerts, cards and OpenAPI reference pages rendered with Swagger UI or Redoc.

Search is one of three options: Google Custom Search (the default, which needs the site to be public and crawled), Algolia DocSearch in a pop-up, or Lunr, an offline index built with the site and searched in the browser. Translations are separate content folders per language. Older versions are not built into one site: each version is deployed on its own, and params.versions adds a drop-down that links between them, with a banner for archived ones. Since 0.15 (May 2026) Docsy can also write a Markdown copy of each page and an llms.txt per site for AI agents, a feature its docs still call experimental.

Google open-sourced Docsy in 2018 for its own open-source projects, and it became the default look of cloud-native documentation: kubernetes.io, etcd, OpenTelemetry, Flux, gRPC and Dapr use it, and the project counted 2,200 dependent projects on GitHub at the end of 2024. In August 2026 it moved to the Linux Foundation as a series of LF Projects, LLC, with its repositories now under github.com/docsy.

Why teams pick it

  • Free and self-hosted: the output is static HTML, so any host or CDN can serve it and no vendor account is involved
  • Builds on Hugo, so even sites with thousands of pages build quickly; kubernetes.io has over 5,600 pages in more than 15 languages
  • Documentation features out of the box: sidebar from the folder tree, page edit links, translations including right-to-left, version drop-down, print view, feedback widget and blog
  • Widely used by CNCF and Google projects, so contributors to those projects already know its layout and shortcodes

Watch out for

  • Still at 0.x: almost every release ships an upgrade guide with breaking changes, such as 0.18 removing jQuery and failing builds that still set params.mermaid
  • Needs a toolchain: Hugo extended 0.160.1 or newer, Go and Git for Hugo modules, and Node.js with npm for Bootstrap, Font Awesome and Dart Sass
  • Versioned docs are separate deployments you build and host yourself; the theme only links them
  • No search of its own: the default, Google Custom Search, finds pages only once Google has crawled the live site, Algolia needs an account, and the docs suggest the offline Lunr index for smaller or non-public sites

Alternatives

What all documentation sites have in common →Compare side by side →
MintlifyCommercialA hosted documentation platform: MDX pages and a docs.json file in your Git repository become a docs site with an API playground generated from OpenAPI, search, and llms.txt, Markdown and MCP access for AI agents.

How it fits with other technologies

hugo.yaml: import Docsy as a Hugo module, use offline search and publish Markdown copies for agents · yaml

baseURL: https://docs.example.org/
title: Example docs
contentDir: content/en

module:
  hugoVersion: { extended: true, min: 0.160.1 }
  imports:
    - path: github.com/docsy/docsy/theme

outputs:
  home: [HTML, print, RSS, markdown, LLMS]   # markdown and LLMS write index.md files and llms.txt
  page: [HTML, markdown]
  section: [HTML, print, RSS, markdown]

params:
  github_repo: https://github.com/example/docs
  offlineSearch: true          # Lunr index built with the site, no external service
  version_menu: Releases
  versions:
    - { version: v2, url: https://docs.example.org/ }
    - { version: v1, url: https://v1.docs.example.org/ }

See it in a real stack

No architecture uses Docsy yet. Drop it into the playground and wire it up yourself.Open playground →
Where it came from2018–2026

Google supports thousands of open-source projects, and they kept asking for tools and guidance to write and publish documentation. Google’s answer was Docsy, a Hugo theme with the structure a technical documentation set needs already in place, plus an example site and guidance on organising pages and accepting contributions. The repository opened in October 2018, and Google announced the theme in July 2019 with the Kubeflow, Knative and Agones sites already built on it.

Cloud-native projects adopted it widely. By January 2023 most CNCF projects that used Hugo used Docsy, and projects such as The Update Framework and in-toto later moved to it with a CNCF Docsy starter. The theme moved to Bootstrap 5, added dark mode in 2024 and grew from 1,400 to 2,200 dependent projects that year; Kubernetes started upgrading from Docsy 0.2.

In August 2026 Docsy became a series of LF Projects, LLC, run by its steering committee, and the repositories moved from google/docsy to github.com/docsy. Erin McKean of Google, a steering committee member, announced the move at Open Source Summit Europe in October 2026 alongside 0.18.0, which also dropped jQuery and made Mermaid, MarkMap and two other scripts optional plugins.

Why it’s built this way

A theme for an existing generator, not a new tool
Building on Hugo gave projects fast builds, Markdown content and free static hosting, so Docsy only had to supply the documentation layout and conventions.
The site’s structure comes from the folder tree
Contributors add a page by adding a Markdown file in the right folder; the sidebar, breadcrumbs and section indexes follow without a separate navigation file to keep in sync.
Versions as separate sites
Each release’s docs can be built from its own branch and frozen, and the theme only needs a list of URLs to offer a version menu and an archived-version banner.
Markdown output for agents, built on Hugo output formats
Rather than a second pipeline, Docsy adds templates so the same build writes index.md beside each index.html and an llms.txt per site.

Timeline

  1. 2018

    Google opens the Docsy repository in October

  2. 2019

    Google announces Docsy in July; Kubeflow, Knative and Agones already use it

  3. 2023

    Most Hugo-based CNCF project sites use Docsy

  4. 2024

    Dark mode with Bootstrap 5.3; dependent projects grow from 1,400 to 2,200

  5. 2026

    Agent support in 0.15 (May); becomes an LF project in August; 0.18 in October drops jQuery

Sources11 · facts checked 28 October 2026

Improve this page on GitHub