Skip to content

Documentation style guide

How to write docs pages and posts for this workspace: tone, headings, callouts, tags, and media.

General guidelines

  • Write concise, direct, factual content in Sentence case (no Title Case for headings or titles).
  • Use American English spelling.
  • Use git history and the generated last-modified footer for editorial dates. Do not add manual “Research date,” “Reviewed,” “Updated,” or “Checkpoint” datelines. Preserve dates that identify source publications, versions, measurements, or other substantive evidence; retain capture timestamps in evidence artifacts.
  • Run just lint-prose for the small set of automated terminology and spelling checks. See Prose rules for scope and quotation exceptions.
  • Prefer linking to other pages over repeating content.
  • Give each topic one maintained home, following the content architecture. Update current guidance in place; preserve completed experiments as labeled historical evidence. Keep installation instructions separate from proposed plugin behavior.
  • Distinguish implemented capabilities from demonstrated behavior and independently validated quality. Installer targets are not proof of harness compatibility; catalog counts are not completed audit coverage. Keep current status in the implementation assessment, acceptance gates in the roadmap, and actionable items in the backlog. Update related landing-page summaries when status changes.
  • Link WSG guideline and criterion references to their actual fragment identifiers in https://www.w3.org/TR/web-sustainability-guidelines/. A bare section number such as “WSG 2.11” is insufficient when the section can be linked directly.
  • Audit reports follow the sustainability-report skill's writing guide: use plain action titles, explain technical limits, and link findings to a readable evidence appendix. Show decimal sizes as kB/MB, not KB; keep raw artifact labels in reproduction details.
  • Use Bulleted lists when describing more than two comparable things or steps.
  • One thing per paragraph; don't be afraid of whitespace.

Callouts and blockquotes

Use Material's admonitions for callouts, with { .info }-style classes where needed:

!!! note "Optional title"

    Content of the callout.

Collapsible callouts use ??? instead of !!!.

Tags

Use short, consistent topic tags to connect related pages in the tag index. Add page-specific tags in front matter:

---
tags:
  - interviews
---

For tags shared by a section, create a .meta.yml file in that folder:

docs/knowledge-base/.meta.yml
tags:
  - knowledge-base

The meta plugin applies these values to the folder and its subfolders. Page tags and folder tags are merged and deduplicated. Use a visible callout to explain draft status; tags alone do not describe what remains unfinished.

Search controls

Use search ranking sparingly. A maintained overview can have a small boost so readers find it before detailed notes:

---
search:
  boost: 2
---

Use boost: 0.5 to reduce an archived page's prominence while keeping it searchable. To exclude a page from search entirely, use:

---
search:
  exclude: true
---

These settings can also go in .meta.yml to apply to an entire folder. Search exclusion does not unpublish a page or restrict access to it. Keep useful source notes searchable unless there is a concrete reason to exclude them. See Material's search controls.

Tables

Use tables for comparisons with consistent fields. Keep column headings descriptive and cells short; use prose for complex explanations. Standard Markdown tables are already enabled by MkDocs:

| Method     | Useful for            | Limitation        |
| ---------- | --------------------- | ----------------- |
| Interviews | Exploring motivations | Small samples     |
| Surveys    | Comparing responses   | Limited follow-up |

Footnotes

Use footnotes for supporting detail that would interrupt the main argument. Prefer an inline source link when it makes a claim easier to verify. Give each note a descriptive identifier:

The sample covers two project teams.[^sample]

[^sample]: Recruitment was limited to teams participating in the pilot.

Landing-page grids

Use a card grid when a landing page needs short descriptions of several equally important destinations. Prefer an ordinary list for a few simple links. The required attr_list and md_in_html extensions are already enabled.

This example is relative to docs/index.md:

<div class="grid cards" markdown>

- **Knowledge base**

    Background research and reusable reference material.

    [Browse the knowledge base](knowledge-base/README.md)

- **Feasibility study**

    Research and design proposals for agentic sustainability audits.

    [Read the feasibility study](feasibility-study/README.md)

</div>

Keep links descriptive, retain a logical reading order, and use text rather than icons alone to identify destinations. See Material's grid reference.

Abbreviations

Shared definitions live in contributing/abbreviations.md and use Python-Markdown's *[NAME]: Expansion syntax. For example, PSF and WG have definitions in the template. Define unfamiliar terms in the prose on first use as well.

The definitions file is excluded from page generation and from Prettier, which otherwise rewrites the abbreviation markers. Keep the leading asterisk when editing it.

Code blocks

Fence code blocks with the language for syntax highlighting. Add a title for context:

```python title="example.py"
print("Hello")
```

Link to other docs pages with relative Markdown links ([Contributing](README.md)). Avoid root-relative paths such as /contributing/: the strict build rejects them, and they omit the repository path on GitHub Pages. Use full URLs for external sources.

Cite external projects using their canonical documentation or upstream repository, even when research uses a local checkout. Public source citations must not rely on local/ directories, absolute workstation paths or file:// links. Verify repository ownership from the checkout's remotes and upstream project metadata. For version-specific source claims, prefer a commit permalink and confirm that the commit and file exist in that repository before replacing a fork link.

A fork-only change or dirty working tree is distinct evidence: identify it explicitly and link published artifacts or the actual fork where available. An upstream commit does not prove it contains uncommitted changes. Preserve exact paths and hashes inside frozen evidence artifacts when needed for reproducibility; use clearly labeled placeholders in general source-directory examples.