🎨

Strapi Documentation Style Guide

🚀
The Strapi documentation is based on Docusaurus, and the formatting options are a mix of basic MarkDown or HTML, and custom React components. Below are listed all these content formatting options as well as guidelines and best practices to follow when writing for Strapi CMS Documentation, or Cloud Documentation.

Content formatting

Titles

MARKDOWN

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

There is only one H1 title, at the very beginning of the documentation file. Other titles can be used several times throughout the file but must keep a logical order (e.g. H3 shouldn’t be used if there is no H2 before).

🚀
Best practices
  • 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.
  • Titles should all have a similar format, especially titles of the same level.
  • 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 by default in main navigation)

## H2 title (displayed by default in main navigation)

### H3 title (displayed by default in secondary navigation)

#### H4 title (displayed by default in secondary navigation)

##### H5 title (by default not displayed in any navigation — should be avoided)

Text highlights

MARKDOWN

Text highlights are basic formatting that represent and/or highlight 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/Admonitions

REACT COMPONENT

Callouts (also called admonitions) 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 allowing to successfully complete a full procedure
    • image
  • Additional information (”Strapi callout”): for Strapi-related facts or links to other Strapi resources. Potentially aiming at promoting the Strapi ecosystem in a more marketing-like way. It should only be used by the Strapi team.
    • 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
⚠️
There must be no space between ::: and the name of the callout.
:::tip
[content goes here]
:::
:::note
[content goes here]
:::
:::prerequisites
[content goes here]
:::
:::strapi
[content goes here]
:::
:::caution
[content goes here]
:::
:::warning
[content goes here]
:::

Links

MARKDOWN

Links can redirect users to other parts/sections of https://docs.strapi.io/ (internal links) and to any other resource outside the Strapi documentation (external links).

🚀
Best practices
  • If the name of the doc/section to link is already in the sentence, directly put the link on that doc/section name. Otherwise, add the name of the related doc + the link in parenthesis in the following format: (see [doc name](link)).
  • Consider links as IDs not paths: do not add the extension at the end of the file name (e.g. content-manager.md → content-manager).
  • If a file had a slug property defined, use its value as ID.
  • Use absolute links instead of relative ones for more stability & reliability (e.g. ../features/content-history → /cms/features/content-history).
Each collection type is divided into 2 interfaces: the list view and the edit view (see [Writing content](writing-content)).

Strapi does not support and does not recommend using any external databases, though it's possible to configure one (see [advanced database configuration](/cloud/advanced/database)).
👆 Internal links
All formatting options are in the [style guide](https://www.notion.so/strapi/Strapi-docs-style-guide-b9c21387732741ed8b0a3f9701612577).
👆 External links

Lists

MARKDOWN

Lists display information in a clearer, more readable way than in an enumeration or full paragraph.

  • Bullet lists are for same-level items. They are used to avoid enumerations.
  • Numbered lists are for procedures. Each number describes an action that will lead the user to complete a goal.

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

🚀
Best practices
  • For bullet lists — 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).
  • For numbered lists — Always start with a capital letter and end with a full stop.
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.
👆Bullet list
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.
👆Numbered list (procedure)

Code examples

REACT COMPONENT

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

It is possible to add a title to the code example, to indicate the file where the code is/should be located/written.

There are 2 options for code examples:

  • Simple:
    • image
  • Simple with title:
    • image
  • Advanced, which are mixed with tabs to display various language/environment options:
    • image
🚀
Best practices

For better cross-page syncing, use the following groupId and value properties for advanced code examples:

  • Use case: YARN vs. NPM
    • groupId : yarn-npm
    • value properties : yarn and npm
  • Use case: JavaScript vs. TypeScript
    • groupId : js-ts
    • value properties : js and ts
  • Use case: axios vs. fetch
    • groupId : axios-fetch
    • value properties : axios and fetch
```language
[code goes here]
```
👆 Simple code example
```language title="./src/api/[api-name]/content-types/restaurant/schema.json"
[code goes here]
```
👆 Simple code example with title
<Tabs groupId="GROUP-NAME">

<TabItem value="NAME-TAB-1" label="LABEL-1">
```language
[code goes here]
```
</TabItem>

<TabItem value="NAME-TAB-2" label="LABEL-2">
```language
[code goes here]
```
</TabItem>

</Tabs>
👆 Advanced code example with tabs for languages

Details

HTML

Details are blocks that by default only display a title, as the rest of the content is collapsed. It is used for additional examples that are not essential and can therefore be hidden by default to make the documentation shorter and cleaner.

image
image
<details>
<summary>Title of the details block</summary>

``` [code goes here]
```

</details>

Tables

MARKDOWN

Tables display more 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

REACT COMPONENT

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

image
<Tabs groupId="GROUP-NAME">

<TabItem value="NAME-TAB-1" label="LABEL-1">
[content goes here]
</TabItem>

<TabItem value="NAME-TAB-2" label="LABEL-2">
[content goes here]
</TabItem>

</Tabs>

Requests & Responses

REACT COMPONENT

This component displays API requests and responses examples in an API documentation-like style.

Request and Response can be used in 2 ways:

  • as standalone components,
  • or wrapped in an ApiCall component.

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

image
<ApiCall>

<Request>

`request goes here`

</Request>

<Response>

```language
[code goes here]

```

</Response>

</ApiCall>

Cards

REACT COMPONENT

Cards are used to highlight redirections to other parts of the documentation, or other Strapi resources.

image
image
<CustomDocCardsWrapper>

<CustomDocCard icon="ICON" title="TITLE" description="CONTENT HERE" link="/cms/..." />

<CustomDocCard icon="ICON" title="TITLE" description="CONTENT HERE" link="/cms/..." />

</CustomDocCardsWrapper>
👆 Wrapped cards
<CustomDocCard emoji="ICON" title="TITLE" description="CONTENT HERE" link="https://strapi.io/blog/article-url" />
👆 Independent cards

Specific formatting

Badges

REACT COMPONENT

Badges are added under a title to indicate the specificity of the following content/described feature.

There are 2 types of badges with various options:

  • Pricing badges, to indicate the features and actions restricted to the paid plans, as opposed to the free plan.
  • Release badges, to notify users if a feature is in alpha, beta or under a feature flag.
image
image
<EnterpriseBadge />
<GrowthBadge />

<SsoBadge />
👆 CMS pricing & add-ons badges
<CloudScaleBadge />
<CloudProBadge />
<CloudEssentialBadge />
👆 Cloud pricing badges
<AlphaBadge />
<BetaBadge />

<FeatureFlagBadge />
👆 Release badges

Identity Cards

REACT COMPONENT

In the Features section of the CMS documentation, every page starts with the identity card of the feature or plugin that is documented in that page.

image
image
<IdentityCard>
  <IdentityCardItem icon="credit-card" title="Plan">INFORMATION ON PLANS</IdentityCardItem>
  <IdentityCardItem icon="user" title="Role & permission">REQUIRED ROLES & PERMISSIONS</IdentityCardItem>
  <IdentityCardItem icon="toggle-right" title="Activation">FEATURE AVAILABILITY & ACTIVATION</IdentityCardItem>
  <IdentityCardItem icon="desktop" title="Environment">DEVELOPMENT AND/OR PRODUCTION ENVIRONMENT</IdentityCardItem>
</IdentityCard>
👆 Identity card for features
<IdentityCard isPlugin>
  <IdentityCardItem icon="navigation-arrow" title="Location">PLUGIN LOCATION</IdentityCardItem>
  <IdentityCardItem icon="package" title="Package name">`package_name`  </IdentityCardItem>
  <IdentityCardItem icon="plus-square" title="Additional resources"><ExternalLink to="https://market.strapi.io/plugins/link-to-marketplace" text="LINK TEXT"/> </IdentityCardItem>
</IdentityCard>
👆 Identity card for plugins

Snippets

REACT COMPONENT

Snippets allow effectively reusing 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.

Snippets are stored in the docusaurus/docs/snippets folder.

🚀
Best practices
  • Import the snippet at the beginning of the documentation file, right before the H1 title.
  • The name of the snippet in the page can be decided by the writer, as long as it remains the same throughout the whole file.
import SnippetName from '/docs/snippets/snippet-file-name.md'

(...)

<SnippetName components={props.components} />

Illustrations

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 static/img/assets folder, in the SVG format, and should be integrated in the documentation files as images.

💡
Icons used in the documentation are from Phosphor. Use the search to know what the name of the right icon is.
⚠️
Emojis should not be used in the documentation. Always opt for icons.
image
<Icon name="icon_name" />

Screenshots

Screenshots are mostly used to show what happens in the admin panel. They are generally displayed after an introduction-type sentence, and before the explanatory content. One screenshot per section is generally enough.

All screenshots are stored in the static/img/assets folder at the root of the Docusaurus documentation folder. They are grouped in various sub-folders named after documentation sections or features.

🚀
Best practice
  • 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 (#8c4bff), and its lines should be 3px wide.
⚠️
All screenshots need to be available in both Light Mode and Dark Mode.
<ThemedImage
  alt="IMAGE CAPTION"
  sources={{
    light:'/img/assets/.../my-image.png',
    dark:'/img/assets/.../my-image_DARK.png',
  }}
/>
image

Guideflows

Guideflows are interactive demos that users can follow step by step. They are mostly used to show Strapi features and are usually added at the beginning of each feature page (after the identity card).

Since an account is needed, only the Strapi team should add new Guideflows or update them.

⚠️
All Guideflows need to be available in both Light Mode and Dark Mode.
image