AGENTS.md

AGENTS.md — TYPO3 "How to Document" Guide

Repo structure

Documentation/                   # the actual manual (reST source, published to docs.typo3.org)
├── Advanced/ContentStyleGuide.rst   # official writing style guide (sentence case, spelling, capitalization)
├── Advanced/CodingGuidelines.rst    # reST formatting conventions (indentation, markers)
├── Reference/ReStructuredText/      # reST syntax reference (roles, directives, anchors, code blocks, ...)
└── ...
CONTRIBUTING.rst                 # how to contribute (issues, branching, PRs)

Commands

• make docs — render the manual locally with Docker
• make test-docs — render in minimal-test mode (the same validation CI runs); use this to validate any change before committing

Rules

1. reST, not Markdown — everything under Documentation/ is reStructuredText.
2. Sentence case headlines — first word and proper nouns only; see Documentation/Advanced/ContentStyleGuide.rst.
3. 4-space indentation for directive bodies, 2 spaces after .. markers; see Documentation/Advanced/CodingGuidelines.rst.
4. Single backticks over double, unless the content needs a literal backtick; see Documentation/Reference/ReStructuredText/Code/InlineCode.rst.
5. Every headline needs a .. _anchor: target directly above it; see Documentation/Reference/ReStructuredText/Links/Anchors.rst.
6. Link TYPO3 documentation with permalinks, also inside the same manual: `link text <https://docs.typo3.org/permalink/<interlink>:<anchor>>`_. Do not suggest replacing a permalink with :ref:; existing :ref: links can stay. Every link needs its own link text, never :ref:`anchor`. See Documentation/Reference/ReStructuredText/Links/Documentation.rst.
7. Validate before committing — run make test-docs.
8. Never commit or push without being asked.
9. Commit message: follow Documentation/Advanced/CommitMessages.rst. This repo has only main (no LTS branches), so skip Releases:. If the change resolves an issue, add Resolves: #<number>.
10. Pull request: the title is the commit's summary line and the description is the commit body, trailers included, as plain wrapped text. Add nothing else: no Markdown lists, no generated-by footer.

References

• CONTRIBUTING.rst — contribution workflow
• Documentation/Advanced/CommitMessages.rst — commit message conventions
• Documentation/Advanced/ContentStyleGuide.rst — official writing style guide
• Documentation/Advanced/CodingGuidelines.rst — reST formatting conventions
• Documentation/Reference/ReStructuredText/ — reST syntax reference (roles, directives, anchors, code blocks, ...)