Skip to content

Contribute to the Documentation

Writing guide

Follow FAIRmat's NOMAD Docs Writing Guide for anything you write here. In short:

  • Structure by Diátaxis: a tutorial (learning-oriented, step-by-step), a how-to guide (goal-oriented, practical), an explanation (understanding-oriented, background), or a reference (information-oriented, precise). Identify which one you're writing before you start -- a page that mixes them is harder to navigate, not more complete.
  • Write for the reader's task, not the codebase's layout. Be as detailed as needed, as concise as possible; state prerequisites up front.
  • Stay consistent: canonical names (NOMAD, NOMAD Oasis, NORTH), backticks for code/file names/literal values, "double quotes" for UI text/labels/error messages, bold for UI elements and important emphasis, italics for first-introduced terms.
  • Links: descriptive text, never bare here/link; internal links use path-hierarchy names ([How-to > Install this Plugin](...)); external links open in a new tab ({:target="_blank" rel="noopener"}). Broken links fail CI -- fix them, or open an issue if you can't.
  • Admonitions: standard titles only (e.g. !!! warning "Attention", !!! tip "Important"); no custom ones.
  • Images sparingly -- each one is long-term upkeep. Prefer content you can express in code: Mermaid diagrams first, then SVG, then JPG as a last resort.
  • Verify against the real system before merging -- commands, output, and examples should match what actually happens.

Build the docs locally

Docs dependencies are part of the dev extra (see How-to guides > Contribute to this Plugin > Development installation), so if you've already run uv pip install -e ".[dev]", you're set. Serve the site locally with live-reload:

mkdocs serve

Before opening a PR, it is recommended to build with --strict so broken links/nav entries fail locally instead of in CI (.github/workflows/mkdocs-deploy.yml):

mkdocs build --strict

Add a new page

  1. Pick the right section -- this repo's docs/ layout already mirrors the Diátaxis categories:
Directory Kind
docs/tutorial/ Tutorials
docs/how_to/ How-to guides
docs/explanation/ Explanation
docs/reference/ Reference
  1. Add the Markdown file in that directory.
  2. Register it in the nav in mkdocs.yml -- a page not listed there won't appear in the site, even if it builds.
  3. Images/data: put a page's assets in an images//data/ subdirectory next to that page, not shared across pages -- e.g. docs/how_to/images/my-diagram.svg.
  4. Preview with mkdocs serve and check the page renders and the nav entry shows up where you expect.