Project and website documentation on Docsy

Style guide

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

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 …