symfony-docs-contribution

When to Activate

Use when writing or editing reStructuredText (.rst) documentation for symfony/symfony-docs or for a Symfony package's own docs (bundles, UX, AI, ...). Covers RST syntax, the documentation writing standards, and the doc PR workflow.

For PHP code changes, use the symfony-code-contribution skill instead.

Core Rules

1. US English, second person, gender-neutral. Write American English (Merriam-Webster), address the reader as "you" (never "we"), use they/them rather than he/she.
2. RST, not Markdown. Double backticks for inline code, list markers flush to the line start, .. code-block:: <lang> for code. Single backticks and indented lists are Markdown habits — don't.
3. Wrap prose at ~80 chars, code examples at ~85. Define hyperlinks at the bottom of the page — no inline link targets.
4. Title Case headings with the correct underline character per level (see below).
5. Realistic code examples that follow the Symfony coding standards and best practices — no foo/bar; use Acme as the vendor and example.com/.org/.net as domains.
6. Target the right branch and keep one topic per PR. Docs are licensed CC BY-SA 3.0.

reStructuredText Format

Headers — underline (and for level 1, overline) with the text's exact width:

Level	Char	Placement
1	=	over and under
2	-	under
3	~	under
4	.	under
5	"	under

Lists start at column 0 (no indentation). - or * for unordered, numbers for ordered.

Code blocks — .. code-block:: <lang> then an indented block; default language is PHP. Common languages: php, yaml, xml, twig, html+twig, html+php, bash, terminal, json, diff, text, env, php-symfony, php-standalone, php-attributes.

.. code-block:: yaml

    framework:
        secret: '%env(APP_SECRET)%'

Multi-format config — show a config in several formats with .. configuration-block:: wrapping nested .. code-block:: directives. Use .. tabs:: / .. tab:: Name for tabbed content (e.g. install methods).