Add Support for Documentation Insets / Admonitions in design documentation
Problem
Currently, we have a special way of highlighting a "todo" within the documentation on design.GitLab.com. This is however not usable for other content that may need special highlighting such as notes, tips, important, warnings, etc.
Usecase
When writing documentation it is useful to call out specific items which may be an important concept or an admonition to the user for a common pitfall.
Examples
Sphinx allows this functionality via custom theming of admonitions; see this presentation slide 13 for an example.
Another example from StackOverflow.
Proposal
Implement a similar, but different, styling as todos, but for other highlighted content.
Original description
It is common when writing documentation to add an inset box with some kind of admonition to the user.
This practice comes from the world of textbooks where concepts that are often misunderstood or that are very important are highlighted in more detail.
Sphinx provides this via its use of admonition. Custom admonitions may be defined and styled in the CSS by the documentation team.
The common use cases are:
- Note
- Tip
- Important
- Warning
- Caution
Each of these should have a definitive style and, in my opinion, should have basic overrides from the Markdown.
So let's say "Note" is an example, we'd get a nice box in an offset colour from the main background with Note as the box title. The markdown might look like:
> ..Note
It would be useful to allow projects to add admonitions with styling and pre-selected header text in the same way we allow users to define labels and colors.