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 (with MyST) and reStructuredText. We encourage writing documentation in Markdown first, and only reaching for more advanced reStructuredText formatting if there is a compelling reason. Docstrings in Python code must be written in reStructuredText, as using Markdown is not yet supported.

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

Paragraphs

It all starts here. Keep your sentences short, varied in length.

Separate text with an empty line to create a new paragraph.

Latin phrases and abbreviations

Try to avoid Latin phrases (such as ergo or de facto) and abbreviations (such as i.e. or e.g.), and use common English phrases instead. Alternatively, find a simpler way to communicate the concept or idea to the reader. The exception is etc. which can be used when space is limited.

Examples:

Don’t use this

Use this instead

e.g.

for example, such as

i.e.

that is

viz.

namely

ergo

therefore

Heading levels

Use heading levels to create sections, and allow users to link straight to a specific section. Start documents with an # h1, and proceed with ## h2 and further sub-sections without skipping levels.

# Heading level 1

## Heading level 2

### Heading level 3

Lists

Use bullets for unordered lists, numbers when ordered. Prefer dashes - for bullets. Nest by indenting with 4 spaces.

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

1. Numbered list 1
2. Numbered list 2
3. Numbered list 3
Rendered output

  • Bullet 1

  • Bullet 2

    • Nested bullet 2

  • Bullet 3

  1. Numbered list 1

  2. Numbered list 2

  3. Numbered list 3

Inline styles

Use bold and italic sparingly and inline code when relevant.

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

Keep in mind that in reStructuredText, italic is written with *, and inline code must be written with double backticks, like ``code``.

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

Code blocks

Make sure to include the correct language code for syntax highlighting, and to format your code according to our coding guidelines. Frequently used: python, css, html, html+django, javascript, sh.

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

When using console (terminal) code blocks

Note

$ or > prompts are not needed, this makes it harder to copy and paste the lines and can be difficult to consistently add in every single code snippet.

Use sh as it has better support for comment and code syntax highlighting in MyST’s parser, plus is more compatible with GitHub and VSCode.

```sh
# some comment
some command
```
Rendered output 
# some comment
some command

Use doscon (DOS Console) only if explicitly calling out Windows commands alongside their bash equivalent.

```doscon
# some comment
some command
```
Rendered output 
# some comment
some command

Code blocks that contain triple backticks

You can use three or more backticks to create code blocks. If you need to include triple backticks in a code block, you can use a different number of backticks to wrap the code block. This is useful when you need to demonstrate a Markdown code block, such as in the examples above.

````md
```python
print("Hello, world!")
```
````
Rendered output 
```python
print("Hello, world!")
```

Note and warning call-outs

Use notes and warnings sparingly to get the reader’s attention when needed. These can be used to provide additional context or to warn about potential issues.

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

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

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)
Rendered output

The TableBlock component in StreamField, with row header, column header, caption fields - and then the editable table

Docstrings and API reference (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.

Modules, classes, and functions can be documented with docstrings. Class and instance attributes can be documented with docstrings (with triple quotes """) or doc comments (with hash-colon #:). Docstrings are preferred, as they have better integration with code editors. Docstrings in Python code must be written in reStructuredText syntax.

SLUG_REGEX = r'^[-a-zA-Z0-9_]+$'
"""Docstring for module-level variable ``SLUG_REGEX``."""

class Foo:
    """Docstring for class ``Foo``."""

    bar = 1
    """Docstring for class attribute ``Foo.bar``."""

    #: Doc comment for class attribute ``Foo.baz``.
    #: It can have multiple lines, and each line must start with ``#:``.
    #: Note that it is written before the attribute.
    #: While Sphinx supports this, it is not recommended.
    baz = 2

    def __init__(self):
        self.spam = 4
        """Docstring for instance attribute ``spam``."""

The autodoc extension provides many directives to document Python code, such as autoclass, autofunction, automodule, along with different options to customize the output. In Markdown files, these directives need to be wrapped in an eval-rst directive. As with docstrings, everything inside the eval-rst block must be written in reStructuredText syntax.

You can mix automatic and non-automatic documentation. For example, you can use module instead of automodule and write the module’s documentation in the eval-rst block, but still use autoclass and autofunction for classes and functions. Using automatic documentation is recommended, as it reduces the risk of inconsistencies between the code and the documentation, and it provides better integration with code editors.

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

    Wagtail's core utilities.

    .. autofunction:: cautious_slugify
        :no-index:
```
Rendered output

Wagtail’s core utilities.

wagtail.coreutils.cautious_slugify(value)

Convert a string to ASCII exactly as Django’s slugify does, with the exception that any non-ASCII alphanumeric characters (that cannot be ASCIIfied under Unicode normalisation) are escaped into codes like ‘u0421’ instead of being deleted entirely.

This ensures that the result of slugifying (for example - Cyrillic) text will not be an empty string, and can thus be safely used as an identifier (albeit not a human-readable one).

For more details on the available directives and options, refer to Directives and The Python Domain in Sphinx’s documentation.

Tables

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

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

Browser

Device/OS

Stock browser

Android

IE

Desktop

Safari

Windows

Tables of contents

The toctree and contents directives can be used to render tables of contents.

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

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

Version added, changed, deprecations

Sphinx offers release-metadata directives to present information about new or updated features in a consistent manner.

```{versionadded} 2.15
The `WAGTAIL_NEW_SETTING` setting was added.
```

```{versionchanged} 2.15
The `WAGTAIL_OLD_SETTING` setting was deprecated.
```
Rendered output

Added in version 2.15: The WAGTAIL_NEW_SETTING setting was added.

Changed in version 2.15: The WAGTAIL_OLD_SETTING setting was deprecated.

These directives will typically be removed two releases after they are added, so should only be used for short-lived information, such as “The WAGTAILIMAGES_CACHE_DURATION setting was added”. Detailed documentation about the feature should be in the main body of the text, outside of the directive.

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:

Supplementary information

This will be visible when expanding the content.

Formatting to avoid

There is some formatting in the documentation which is technically supported, but we recommend avoiding unless there is a clear necessity.

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 italicized paragraph underneath the image.

Other reStructuredText syntax and Sphinx directives

We generally want to favor 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.

Markdown in reStructuredText

Conversely, do not use Markdown syntax in places where reStructuredText is required. A common mistake is writing Markdown-style inline `code` (with single backticks) inside Python code docstrings and inside eval-rst directives. This is not supported and will not render correctly.

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.

Code example considerations

When including code examples, particularly JavaScript or embedded HTML, it’s important to follow best practices for security, accessibility and approaches that make it easier to understand the example.

These are not hard rules but rather considerations to make when writing example code.

Reference example filename

At the start of a code snippet, it can be helpful to reference an example filename at the top. For example: # wagtail_hooks.py or // js/my-custom.js.

CSP (Content Security Policy) compliance

When adding JavaScript from external sources or custom scripts, ensure CSP compliance to prevent security vulnerabilities like cross-site scripting (XSS).

Avoid mark_safe where possible, and use format_html and use examples that load external files to manage scripts securely instead of inline <script> usage.

Accessibility compliance

Make sure that all examples are accessible and adhere to accessibility standards (for example: WCAG, ATAG).

For interactive components, ensure proper keyboard navigation and screen reader support. When creating dynamic content or effects (such as animations or notifications), provide options for users to pause, stop, or adjust these features as needed.

If needed, call out explicitly that the example is not compliant with accessibility and would need additional considerations before adoption.