Repository-root markdown files

• 1:
• 2:
• 3:

1 -

AGENTS.md — Docsy repo guide for AI agents

For detailed information about the Docsy project structure, branching model, and release process, etc., see:

• The website content tree docsy.dev/content/en/project/ (project)
• Note in particular git-info.md.

Agents should treat those documentation pages as the authoritative source for project CI/CD, release process, etc.

Code, test, and documentation conventions

• Assume that the maintainers and readers of the code you write are senior web developers and designers who know the site’s tools, including Hugo, Bootstrap, etc.
• Brevity is good — in code, comments, and commit messages.
• When you write, think lean and DRY.
• Don’t use comments to explain the obvious; use self-explanatory names and short names when the context is clear.
• This project has a long history; look for existing helpers (partials, shortcodes, SCSS mixins, and similar) before adding new ones.

User guide

Enforce the style guide when reviewing user guide additions or modifications.

Separation of concerns

Note this partitioning of concerns in the docs (to keep things lean and DRY):

• Changelog: see guidelines at the top. Very terse listing of changes; will link to posts to for “Details” links.
• Upgrade blog posts: help clients (humans and agents), know what has changed, what needs upgrading, and when upgrading is needed (for each change)
• The Docs reflect the current Docsy design. No or little historical notes.
• Release message links to the changelog and upgrade blog posts, and lists the actual Git history since the last release.

Monorepo layout

The repo root orchestrates two npm workspaces:

• theme/ — the Docsy theme module (the published Hugo module). Consuming sites import github.com/google/docsy/theme; npm/clone installs use theme: docsy/theme. theme/package.json owns Bootstrap and Font Awesome.
• docsy.dev/ — the project website (this content tree).

Releases publish a nested module tag theme/vX.Y.Z alongside vX.Y.Z.

Release prep

Release prep is driven by the docsy-release-artifacts skill, with a living workspace under tasks/VERSION/release-prep/ (release coordinates, a coverage ledger, and a wrapup). It tracks every change since the last release and routes each into the right artifact (changelog, release post, Hugo post). Refresh the workspace as commits land; see the skill for the process.

Pull requests

• Before the final push of a PR branch, run npm run set:version:git-info to refresh the package build ID. A pre-push hook also runs this and will abort the push if the ID changed, so doing it yourself avoids a failed push.

2 -

Changelog

The changelog is published online, see Changelog or the page source.

3 -

Docsy

Docsy is a Hugo theme for technical documentation sets, providing simple navigation, site structure, and more.

This is not an officially supported Google product. This project is actively being maintained.

Prerequisites

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

• Install a recent release of the Hugo “extended” version. If you install from the Hugo release page, make sure you download the extended version, which supports SCSS.

• Install PostCSS so that the site build can create the final CSS assets. You can install it locally by running the following commands from the root directory of your project:

  npm install --save-dev autoprefixer
  npm install --save-dev postcss-cli
  

  Starting in version 8 of postcss-cli, you must also separately install postcss:

  npm install -D postcss
  

Any additional prerequisites depend on the installation option you choose. We recommend using Docsy as a Hugo module, which requires that you have the Go language installed in addition to Hugo and PostCSS.

For complete prerequisites and instructions, see our Get started guides.

Example and usage

You can find an example project that uses Docsy in the Docsy Example Project repo.The Docsy Example Project is hosted at example.docsy.dev. For real-life examples of sites that use Docsy (and their source repos), see our Examples and templates page.

To use the Docsy theme for your own site:

• (Recommended) Use the example project, which includes the Docsy theme as a Hugo module, as a template to create your project. You can customize this pre-configured basic site into your own Docsy themed site. Learn more…

• Add Docsy to your existing Hugo site. You can add Docsy as a Hugo module, as a Git submodule, or clone the Docsy theme into your project.

See the Get started guides for details about the various usage options.

Documentation

Docsy has its own user guide (using Docsy, of course!) with lots more information about using the theme. It is hosted by Netlify at docsy.dev.

Maintainers: you can access deploy logs, the deploy preview of main, and more from the Deploys section of the site’s Netlify dashboard.

Alternatively you can use Hugo to generate and serve a local copy of the guide (also useful for testing local theme changes), making sure you have installed all the prerequisites listed above:

git clone --depth 1 https://github.com/google/docsy.git
cd docsy
npm install
npm run serve

Contributing

For details on our code of conduct and the process for submitting pull requests, see CONTRIBUTING.md. Thank you to all past, present, and future contributors!

License

This project is licensed under the Apache License 2.0, see LICENSE for details.