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
- Text highlights
- Callouts/Admonitions
- Links
- Lists
- Code examples
- Details
- Tables
- Tabs
- Requests & Responses
- Cards
- Specific formatting
- Badges
- Identity Cards
- Snippets
- Illustrations
- Icons
- Screenshots
- Guideflows
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
- Notes: for helpful, time-saving information
- Prerequisites: for necessary conditions allowing to successfully complete a full procedure
- 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.
- Cautions: for important information such as mistakes prevention, recommendations, unstable or unreliable documentation
- Warnings: for highly important information such as data loss, project crash prevention, unsupported documentation
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.mdcontent-manager). - If a file had a
slugproperty 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)).All formatting options are in the [style guide](https://www.notion.so/strapi/Strapi-docs-style-guide-b9c21387732741ed8b0a3f9701612577).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.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 examples
REACT COMPONENT
Details
HTML
Tables
MARKDOWN
Tabs
REACT COMPONENT
Requests & Responses
REACT COMPONENT
Cards
REACT COMPONENT
Specific formatting
Badges
REACT COMPONENT
Identity Cards
REACT COMPONENT
Snippets
REACT COMPONENT