Documentation guidelines

Formatting recommendations
Formatting to avoid

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.

Paragraphs

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

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

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

Numbered list 1
Numbered list 2
Numbered list 3

Inline styles

Use bold and italic sparingly, inline code when relevant.

Use **bold** and _italic_ sparingly, 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, console.

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

Links

Links are fundamental in documentation. Use internal links to tie your content to other docs, and external links as needed. Pick relevant text for links, so readers know where they will land.

Don’t rely on links over code, as they are impossible to spot.

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).

Rendered output

An external link. An internal link to another document. An auto generated link label to a page Your first Wagtail site. A link to a reference.

Reference links

Reference links (links to a target within a page) rely on the page having a reference created, this can be added as follows:

(my_awesome_section)=

##### Some awesome section title

...

The reference can be linked to, with an optional label, using the Markdown link syntax as follows:

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

Rendered output

Some awesome section title

…

Auto generated label (preferred) Some awesome section title
label for section

You can read more about other methods of linking to, and creating references in the MyST parser docs section on Targets and cross-referencing.

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.
```

Rendered output

Note

Notes can provide complementary information.

Warning

Warnings can be scary.

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.

![Screenshot of the workflow editing interface, with fields to change the workflow name, tasks, and assigned pages](/_static/images/screen44_workflow_edit.png)

Rendered output

Screenshot of the workflow editing interface, with fields to change the workflow name, tasks, and assigned pages

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 which we highly recommend using to document Wagtail’s APIs.

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

.. autofunction:: cautious_slugify
```

Rendered output

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

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
```

Rendered output

New in version 2.15.

Changed in version 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:

Supplementary information

This will be visible when expanding the content.