Documentation guidelines¶

Writing style guide¶

To ensure consistency in tone and language, follow the Google developer documentation style guide when writing the Wagtail documentation.

Formatting recommendations¶

Wagtail’s documentation uses a mixture of Markdown and reStructuredText. We encourage writing documentation in Markdown first, and only reaching for more advanced reStructuredText formatting if there is a compelling reason.

Here are formats we encourage using when writing documentation for Wagtail.

# Heading level 1

## Heading level 2

### Heading level 3

-   Bullet 1
-   Bullet 2
    -   Nested bullet 2
-   Bullet 3

1. Numbered list 1
2. Numbered list 2
3. Numbered list 3

Use **bold** and _italic_ sparingly and inline `code` when relevant.

```python
INSTALLED_APPS = [
    ...
    "wagtail",
    ...
]
```

INSTALLED_APPS = [
    ...
    "wagtail",
    ...
]

```sh
# some comment
some command
```

# some comment
some command

```doscon
# some comment
some command
```

# some comment
some command

An [external link](https://wwww.example.com).
An [internal link to another document](/reference/contrib/legacy_richtext).
An auto generated link label to a page [](/getting_started/tutorial).
A [link to a reference](register_reports_menu_item).

(my_awesome_section)=

##### Some awesome section title

...

-   Auto generated label (preferred) [](my_awesome_section)
-   [label for section](my_awesome_section)

Note and warning call-outs¶

Use notes and warnings sparingly, as they rely on reStructuredText syntax which is more complicated for future editors.

```{note}
Notes can provide complementary information.
```

```{warning}
Warnings can be scary.
```

These call-outs do not support titles, so be careful not to include them, titles will just be moved to the body of the call-out.

```{note} Title's here will not work correctly
Notes can provide complementary information.
```

Images¶

Images are hard to keep up-to-date as documentation evolves, but can be worthwhile nonetheless. Here are guidelines when adding images:

• All images should have meaningful alt text unless they are decorative.

• Images are served as-is – pick the correct format, and losslessly compress all images.

• Use absolute paths for image files so they are more portable.

![The TableBlock component in StreamField, with row header, column header, caption fields - and then the editable table](/_static/images/screen40_table_block.png)

Autodoc¶

With its autodoc feature, Sphinx supports writing documentation in Python docstrings for subsequent integration in the project’s documentation pages. This is a very powerful feature that we highly recommend using to document Wagtail’s APIs.

```{eval-rst}
.. module:: wagtail.coreutils

.. autofunction:: cautious_slugify
```

Tables¶

Only use tables when needed, using the GitHub Flavored Markdown table syntax.

| Browser       | Device/OS |
| ------------- | --------- |
| Stock browser | Android   |
| IE            | Desktop   |
| Safari        | Windows   |

Tables of contents¶

toctree and contents can be used as reStructuredText directives.

```{toctree}
---
maxdepth: 2
titlesonly:
---
getting_started/index
topics/index
```

```{contents}
---
local:
depth: 1
---
```

Version added, changed, deprecations¶

Sphinx offers release-metadata directives to generate this information consistently. Use as appropriate.

```{versionadded} 2.15
```

```{versionchanged} 2.15
```

Progressive disclosure¶

We can add supplementary information in documentation with the HTML <details> element. This relies on HTML syntax, which can be hard to author consistently, so keep this type of formatting to a minimum.

<details>
    <summary>Supplementary information</summary>

    This will be visible when expanding the content.
</details>

Example:

Call-outs¶

We only use {note} and {warning} call-outs. Avoid {admonition}, {important}, {topic}, and {tip}. If you find one of these, please replace it with {note}.

Glossary¶

Sphinx glossaries (.. glossary::) generate definition lists. Use plain bullet or number lists instead, or sections with headings, or a table.

Comments¶

Avoid documentation source comments in committed documentation.

Figure¶

reStructuredText figures (.. figure::) only offer very marginal improvements over vanilla images. If your figure has a caption, add it as an italicised paragraph underneath the image.

Other reStructuredText syntax and Sphinx directives¶

We generally want to favour Markdown over reStructuredText, to make it as simple as possible for newcomers to make documentation contributions to Wagtail. Always prefer Markdown, unless the document’s formatting highly depends on reStructuredText syntax.

If you want to use a specific Sphinx directive, consult with core contributors to see whether its usage is justified, and document its expected usage on this page.

Arbitrary HTML¶

While our documentation tooling offers some support for embedding arbitrary HTML, this is frowned upon. Only do so if there is a necessity, and if the formatting is unlikely to need updates.