Style guide

This project follows Google’s developer documentation style guide, and uses Prettier and Markdownlint to enforce basic formatting rules.

Front matter

• Do not quote string values unless doing so would otherwise cause ambiguity or unintended type interpretation.
• Drop linkTitle when it is the same as title.

Content

Alerts

• Prefer Hugo’s blockquote alert syntax over the legacy alert shortcode for new and edited content. Both render similar output, but the blockquote form is better supported by tools and agents, and naturally renders as is in Markdown format for AI agents.

Lists

• Use periods when list items are complete sentences (including imperative steps).
• Omit periods when list items are fragments, labels, or link-only bullets.
• Keep punctuation consistent within each list. When this isn’t possible, ask the author how they prefer reworking the list item text: e.g., by making all sentences complete.

Verb tense

• Use present tense for all content, except as noted below.
• For release and upgrade blog posts:
  • Use present tense when referring to the release itself, for example:

    Docsy 0.14.0 adds …

  • Use past tense only when describing previous releases or pre-release behavior, for example:

    Before Docsy 0.14.0, the navbar was …

• For the Changelog: use past tense; see its style guide.