CI/CD

Agent-support checks

The site has an AFDocs configuration and npm script to generate a scorecard locally:

To generate a fresh scorecard, run each of these commands in separate terminals:

npm run serve
npm run check:afdocs:dev

The latter command saves the generated scorecard to docs/content/agent-support/afdocs-scorecard.txt under docsy.dev/content/en, which will be included in Scorecard examples on the next build.

Note that the scorecard generation is not run as a part of the full CI/CD pipeline. It needs to be run manually.

Read more: AFDocs config file format.

Formatting and lint checks

Prettier formats Docsy and the website files, and Markdownlint lints the Markdown. To run the checks, or to apply automatic fixes:

npm run check
npm run fix

CI runs these checks and the test suites.

Hugo shortcodes

Prettier formats a paired shortcode’s body as Markdown. When the body isn’t Markdown, such as a tabpane’s code, wrap the shortcode:

<!-- prettier-ignore-start -->
{{< tabpane >}}
...
{{< /tabpane >}}
<!-- prettier-ignore-end -->

Workaround for i18n files

The translation files in the i18n directory are formatted using Prettier. But Prettier removes the blank line before the # Feedback section heading. This seems to be a known issue, for example see:

We’ve worked around this bug, and avoided using prettier-ignore directives, by formatting the preceding entry in the YAML file to be a block scalar, like this:

community_guideline: >-
  Contribution Guidelines

This ensures that the blank line is preserved. Hopefully Prettier will be fixed and we’ll be able to remove this hack.

Last modified October 17, 2026: Contribution guidelines: lean the page to its Docsy facts (#2882) (3cf05d3)