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, 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 which 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: