ReadMe

Mon, 01 Jan 0001 00:00:00 +0000

Docsy

Docsy, a Linux Foundation project, is a Hugo theme for technical documentation sites, providing simple navigation, site structure, and more.

🚧 IMPORTANT 🚧

The main branch is under development and not officially supported; use official Docsy releases. For full support details, see Official support limits.

Prerequisites

The following are basic prerequisites for using Docsy in your site:

Changelog

Mon, 01 Jan 0001 00:00:00 +0000

We document breaking changes and release highlights in this page, with maintainer-facing changes summarized at the end of each release section. For the full list of changes of any particular release, see the release notes.

Useful links: Releases & tags, jump to the latest release, and view the milestones.

Style guide

Use past tense when when describing releases.
Generally, start each change entry with a verb (in the past tense). For example: Added, Changed, Deprecated, Fixed.
It’s ok to follow that with “you can now…”. For example:

Feature abc: you can now…".

Maintainer notes

Mon, 01 Jan 0001 00:00:00 +0000

For our main contributing page covering license agreements, code of conduct and more, see Contributing. This page is for maintainers only.

Content placement

Keep project content DRY by writing each fact in the artifact whose purpose and audience it serves. Each artifact links to the more detailed ones rather than restating them:

Changelog: a lean record of what changed, for developers who want a quick overview. No upgrade advice, implementation detail, or background. Entries link to the release report for details and cite a change’s key issues; PRs only when there is no key issue, such as for contributor credit. Maintainer-facing changes get a short For maintainers list at the end of the release section.
Release and upgrade blog posts: what’s new, what to watch out for, and actionable upgrade guidance (the historical narrative). Link to the site docs for current behavior and reference detail. Don’t enumerate PRs and issues; link an open tracker only where it adds follow-up context. Upgrades are a chore, so keep posts maximally actionable yet lean: the release summary reads like a selective table of contents (a link per section with a clause of guiding glue) and each fact appears in one section, its home. Each post targets upgraders coming from the release just before it; a post that assumes otherwise says so. Maintainer-facing changes are summarized in a For maintainers section at the end of the documented changes.
Site docs (docs/): Docsy as it is now. Minimal historical references or links to issues and PRs.
Release notes and milestones: exhaustive records. Generated release notes list every PR, PRs link their motivating issues, and the release milestone gathers the issues resolved. The release notes lead with links to the changelog entry and the release post. Authored artifacts link to these rather than reproducing the enumeration.
Project docs (project/): architecture, design decisions, and quality-net rationale, for maintainers and contributors. Architecture material lands here, not in code comments; a comment keeps a purpose line and links its page.
Test and code comments: local implementation rationale and regression background.

Version values follow the same ownership rule. An evergreen doc that cites a pinned or supported version reads it from the pin’s source of truth: a config param (for example, params.katex.version), or a repo manifest surfaced through a data mount and shortcode (sass-embedded-version reads the root package.json pin), so the page can’t drift from the pin. A dated post freezes its release-specific versions as page front-matter params (a draft’s frozen values must match the live pins: toolchain-versions test), and delegates install and override mechanics to the docs instead of restating commands.

About the project on Docsy

ReadMe

Docsy

Prerequisites

Changelog

Style guide

Maintainer notes

Content placement