Skip to content

AGENTS.md

Latest commit

 

History

History
89 lines (62 loc) · 5.48 KB

AGENTS.md

File metadata and controls

89 lines (62 loc) · 5.48 KB
Raw

AGENTS.md

Project

Dependency-Track documentation site. Built with MkDocs Material, organized per the Diataxis framework.

Context files

Before writing or modifying documentation, read the relevant context files in context/:

  • context/diataxis-contract.md — mandatory. Defines the four content types (tutorials, guides, concepts, reference) and what belongs where. Every doc must fit exactly one type.
  • context/vocabulary.md — canonical terminology. Use these terms consistently.
  • context/briefing.md — product overview and audience.
  • context/source-inventory.md — describes source repo symlinks and existing docs accuracy status.

Documentation structure

docs/
  tutorials/      # Learning-oriented walkthroughs (student perspective)
  guides/         # Task-oriented procedures (experienced user)
    upgrading/    # Version-specific upgrade procedures
  concepts/       # Understanding-oriented background
  reference/      # Information-oriented technical descriptions

Navigation order is defined in docs/.pages and section-level .pages files. Update these when adding new pages. Navigation titles in .pages files must use sentence-style capitalization (capitalize only the first word, proper nouns, and acronyms).

Commands

Always use make targets for building, serving, and linting. Do not run docker, mkdocs, markdownlint-cli2, yamllint, or vale directly. The Makefile is the single source of truth for how these tools are invoked.

Linting

Run the relevant linter after modifying files:

  • Markdown files (docs/**/*.md, context/**/*.md): make lint-markdown
  • Prose quality (docs/**/*.md): make lint-prose. For fast local iteration on a feature branch, make lint-prose-changed lints only files changed vs. the branch's upstream. Scope a full-tree run with VALE_PATHS=...; surface lower-severity hints with VALE_MIN_LEVEL=suggestion.
  • YAML files (mkdocs.yml, .github/**/*.yml, etc.): make lint-yaml
  • Python files (scripts/**/*.py): make lint-python
  • All at once: make lint

Fix all lint errors before considering work complete.

For newly created files, also fix all lint warnings.

Build and preview

  • make serve — live-reload dev server on port 8000.
  • make build — strict production build (fails on warnings).

Always verify new or modified pages render correctly with make build.

Generated documentation

Some reference pages are generated from source repositories. Do not edit these files directly.

  • Configuration properties (docs/reference/configuration/properties.md): generated by scripts/generate_config_docs.py from application.properties in the API server repo. Regenerate with make generate-config-docs APISERVER_PROPERTIES=<path>.
  • Protobuf schemas (docs/reference/schemas/{notification,policy}.md): generated by protoc-gen-doc from proto definitions in the API server repo. Regenerate with make generate-proto-docs APISERVER_DIR=<path>.
  • OpenAPI specs (docs/reference/api/openapi-*.yaml): downloaded from API server CI artifacts via the update-openapi-docs workflow.

Language and style

Follow the Google developer documentation style guide. Vale enforces the machine-checkable subset (Oxford commas, contractions, em-dashes, semicolons, slang, sentence-case headings, date formats, passive voice, banned words). Apply the rest by hand:

  • Short sentences, active voice, common words. Domain terms (CEL, SBOM, outbox) are fine where they carry weight.
  • No idioms, metaphors, or cultural references — readers translate these docs with machine tools.
  • American English spellings (color, organize, behavior, summarize, centralized, normalize).
  • Address the reader as "you", never "the user".
  • No filler or condescension: "simply", "just", "easy", "obvious", "merely", "basically", "please".
  • No positional references ("above", "below", "earlier"). Link to the section by name instead.
  • Descriptive link text. Never "click here", "here", or "this page".
  • "Select" for UI actions, not "click". Bold for UI labels. Backticks for code, commands, paths, env vars, and identifiers.
  • Abbreviations in docs/includes/abbreviations.md need no first-use expansion (MkDocs renders a hover tooltip). Spell out others on first use per page, and add the abbreviation to that file if it spans more than one page.
  • Numbers zero–nine spelled out, 10+ as numerals. Always numerals for versions, ports, durations, and units.

Where Google style conflicts with context/diataxis-contract.md, Diataxis wins. Notably: Tutorials use "we" (tutor-learner partnership) and "will" to set expectations; Guides, Concepts, and Reference use "you" or no pronoun.

Writing conventions

  • Do not modify files in existing-docs/.
  • Do not add files to source/ without instruction.
  • Use ATX-style headings (# Heading), not setext.
  • Inline HTML is allowed (admonitions, tabs).
  • No line length limit for Markdown prose.
  • End linted Markdown files in docs/ and context/ with a single trailing newline (markdownlint MD047).
  • YAML indentation: 2 spaces, no document-start markers.
  • Vale enforces Google developer style and write-good rules. Accepted/rejected terms are in .vale/styles/config/vocabularies/DependencyTrack/.
  • Page-specific images mirror the docs tree under docs/assets/images/: an image used by docs/<section>/<page>.md lives at docs/assets/images/<section>/<page>/<name>.<ext>. Shared assets (e.g. logo.svg) stay at the root of docs/assets/images/.