🎨

Strapi Documentation Style Guide

πŸ‘‹

All available content formatting options and guidelines to follow when writing for Strapi's User Guide or Developer Documentation. DRI: MΓ©gane Lacheny, Pierre Wizla Last update: September 2021

Content formatting

Titles

Titles are the base of a documentation structure, as they allow to shape the content by separating it into coherent sections.

Titles should be short, yet give a clear idea of what topic will be tackled in the related documentation section. Titles shouldn't be a question. Keep in mind that homogeneity is key in technical writing: titles, especially of the same level, should have a similar format.

✏️

Titles can emphasise the action that is tackled in the following documentation by starting with an action verb (e.g. "Writing content", "Creating content-types").

# H1 title (displayed in left navigation)

## H2 title (displayed in left navigation)

### H3 title

#### H4 title

##### H5 title

Text highlights

Text highlights are basic formatting that allow to represent and/or highlight easily items from user interfaces.

  • italics: for admin panel section names, window and field names
  • bold: for button names
  • code style : for small code excerpts, file names and paths (Developer Documentation)
*italics*

**bold**

`code style`

Callouts

Callouts allow to highlight information by separating it from the regular, main content.

From lowest to highest level of importance:

  • Tips: for tips and tricks, useful information but not required to understand how Strapi works
  • image
  • Notes: for helpful, time-saving information
  • image
  • Prerequisites: for necessary conditions that allow to successfully complete a full procedure
  • image
  • Cautions: for important information such as mistakes prevention, recommendations, unstable or unreliable documentation
  • image
  • Warnings: for highly important information such as data loss, project crash prevention, unsupported documentation
  • image
Additional callout: the Strapi special 🀫

For links to other Strapi resources, aiming at promoting the Strapi ecosystem in a more marketing-like way. It should only be used by the Strapi team.

image
::: strapi
[content goes here]
:::
::: tip
[content goes here]
:::
::: note
[content goes here]
:::
::: prerequisites
[content goes here]
:::
::: caution
[content goes here]
:::
::: warning
[content goes here]
:::

Links

  • When the name of the documentation to link to is already used in the sentence: direct link on the name of the documentation
  • For other cases: addition of the name of the related documentation + link in parenthesis at the end of the sentence, in the following format (see [doc name](link))
All formatting options are in the [style guide](https://www.notion.so/strapi/Strapi-docs-style-guide-b9c21387732741ed8b0a3f9701612577).

Documentation is written properly by
following guidelines (see [Strapi docs style guide](https://www.notion.so/strapi/Strapi-docs-style-guide-b9c21387732741ed8b0a3f9701612577)).

Lists

  • Bullet lists: for same-level items, to avoid enumerations If the bullet points are entirely part of a same sentence, avoid starting with a capital letter and end the point with either a comma or nothing. If the bullet points are independent small sentences, the basic grammar rules apply (capital letter and full stop).
  • Numbered lists: for procedures Always start with a capital letter and end with a full stop.
✏️

If the list contains too many items (more than 10) and/or items need additional explanations, use a table instead.

This is the beginning of my sentence which:
- has a first point,
- and a second point.
It is also possible to write my sentence differently.
- A possible way is as shown below.
- Another possible way is like so.

To write a piece of documentation properly, you should:

1. Open Notion.
2. Go to the Documentation Handbook.
3. Read the Strapi docs style guide.

Code excerpts

Code excerpts and command lines are displayed in a terminal-like style, that also contains a "Copy" button for easier use.

It is possible to add one or more language/environment options.

image
<code-group>

<code-block title="LANGUAGE">
```sh
[code goes here]
```
</code-block>

<code-block title="LANGUAGE">
```sh
[code goes here]
```
</code-block>

</code-group>

Requests & Responses

API requests and responses examples are displayed in an API documentation-like style.

image

request and response can be used in 2 ways:

  • as standalone components,
  • or wrapped in an api-call component.
πŸ€“

Only the api-call component is responsive (i.e. the layout is side-by-side only on large viewports while remaining vertical on smaller viewports).

:::: api-call

::: request Optional title

```language
[code goes here]
```

:::

::: response Optional title

```language
[code goes here]
```

:::
::::

Tables

Tables allow displaying clearly complex groups of items related to the same kind of information. They can also replace lists if they become too long (more than 10 items).

In the User Guide, tables are used to document all fields and options of the same interface.

image
| Title 1    | Title 2         | ... |
|------------|-----------------|-----|
| Item 1     | Item 1          | ... |
| Item 2     | Item 2          | ... |
| Item 3     | Item 3          | ... |

Tabs tables

Tabs tables allow displaying concisely one same kind of information available for several use cases.

πŸ€“

Tabs tables should be used with caution as they prevent effective page search: only the content of the first default tab will be taken into account when searching a keyword.

image
:::: tabs card

::: tab USE CASE 1

[content goes here]

:::

::: tab USE CASE 2

[content goes here]

:::

::::

Specific formatting

Pricing badges

Pricing badges allow to notify the features and actions restricted to one or several Strapi pricing plan, as opposed to the free Community plan.

image
<BronzeBadge link="https://strapi.io/pricing-self-hosted"/>
<SilverBadge link="https://strapi.io/pricing-self-hosted"/>
<GoldBadge link="https://strapi.io/pricing-self-hosted"/>

Snippets

Snippets allow to effectively reuse identical content in several places and/or files. They make updates easier and more reliable, since they are done from one single file instead of several.

✏️

The full path to the file containing the snippet should either be: - developer-docs/latest/snippets/some/sub/folders/file_name.md, for the Developer Docs - user-docs/latest/snippets/some/sub/folders/file_name.md, for the User Guide

!!!include(path/to/file_name.md)!!!

Illustrations

Screenshots

Screenshots are mostly used in the User Guide. They are generally displayed after an introduction-type sentence, and before the explanatory content. One screenshot per section is generally enough.

All screenshots are grouped in an assets folder at the root of both the User Guide and the Developer Documentation.

✏️

Prefer screenshots of the whole interface instead of cutting only part of it. It is easier for the user to locate where something is on the interface using the context.

To indicate a specific area of the screenshot that's mentioned in the documentation: edit the screenshot to add a rectangular shape around the area. The shape should be Strapi purple, and its lines should be 3px wide.

πŸ’‘

Nimbus Screenshot is a nice extension to make screenshots and edit/annotate them.

image
![image description](../assets/subfolder/file_name.png)

Icons

Icons are used to replicate those used on Strapi user interfaces (e.g. the admin panel), to help users locate them on the interface. Icons are available in the user-docs/latest/assets/icons folder, in the SVG format, and should be integrated in the documentation files as images.

✏️

For other usages than mimicking Strapi user interfaces icons, it is possible to use FontAwesome icons: <Fa-IconName />

image
![IconName icon](../assets/icons/iconname.svg)

Emojis

Emojis can be used but very sparingly. Avoid using emojis in all documentations. Instead, prefer using them: - as icons in special notices (default), - as icons in section titles, - in more friendly types of documentation (docs sections introductions, docs about Strapi as a company, quick start guides, guideline docs targeting the Community, etc.)

image