- Line wrapping: Most files don't use line wrapping. Each paragraph or sentence is a complete string of text without newline characters. The rationale is that most viewers and editors have configurable soft-wrap abilities, and every author tends to choose a different hard-wrap column.
Admonitions use a combined MkDocs/Bootstrap definition to get acceptable and similar rendering on both Percona.com (Drupal-based) and Render.com.
Percona.com uses Bootstrap 4. Admonitions are styled as Alerts.
Material for MkDocs theme: https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types
General advice
Admonitions are to highlight something special, not to make every point significant. When used in this way, they are ignored in the same way as 'the boy who cried wolf'. But they help to break up large blocks of text, and add a little colour.
-
Use sparingly.
-
Consider whether the same text can be emphasised with normal means (italics or bold).
By using a subset of all MkDocs, we can get some alignment between those and Bootstrap.
| Admonition | MkDocs colour | Bootstrap colour |
|---|---|---|
| Notes, info | Blue | Blue |
| See also | Blue | Turquoise |
| Tip | Green | Green |
| Caution, Warning, Important | Amber | Amber |
| Danger | Red | Red |
| Summary | Turquoise | Turquoise |
Use as a side panel, an 'aside', a note detached from the main flow of the text.
Preferred use is without the label (first form).
!!! note alert alert-primary ""
Text ...
!!! note alert alert-primary "Note"
Text ...
!!! note alert alert-primary "Side topic"
Text ...Uses same type but different label text:
-
Caution: Used to mean 'Continue with care'. Less strong than 'Warning' IMHO.
-
Important: A significant point that deserves emphasis. (MkDocs default for 'important' admonition is green, which is why I don't use it.)
Style:
- MkDocs: Amber with triangle/! icon
- Bootstrap: Yellow with no icon
!!! caution alert alert-warning "Caution"
!!! caution alert alert-warning "Important"Anything that has the potential to damage or compromise a user's data or system.
- MkDocs: Red with bolt icon.
- Boostrap: Red with no icon.
!!! danger alert alert-danger "Danger"Use for tips, hints, non-essential but useful advice. Note that tip renders badly in Percona.com. hint is better and looks the same as tip in Material theme.
!!! hint alert alert-success "Tip"
Tip
!!! hint alert alert-success "Tips"
- One
- Two
!!! hint alert alert-success ""
TipUsed to summarise a block of text (a TLDR).
!!! summary alert alert-info "Summary"Used to highlight other sections or external links.
Group them at the end of the section.
An exception would be when there is an equivalent or closely related section elsewhere.
- MkDocs: Blue with pen icon (same as note).
- Bootstrap: Turquoise with no icon.
!!! seealso alert alert-info "See also"We use the mkdocs-macros plugin for variable expansion. For example, the variable release in variables.yml is used in the code so that the current PMM release number is always up-to-date. (Search the markdown files for {{release}}.)
This plugin can have problems when Jinja-like constructs are used in code. This happens when referring to Docker variables. Workarounds are explained here: https://github.com/fralau/mkdocs_macros_plugin/blob/master/webdoc/docs/advanced.md#solutions
In some places, we have used variables themselves to solve the problem. In others, {% raw %}/{% endraw %} surrounds the conflicting text.
Use HTML for icons:
- For PMM UI (Grafana) icons (
uil-prefix), go to https://iconscout.com/unicons/explore/line, find an icon, select 'Font' and copy the code here. - For Font Awesome (
fa-prefix), go to https://fontawesome.com/icons, find an icon, copy the code.
| Unicons icon code | Description | Used where |
|---|---|---|
| Down chevron | PMM UI | |
| Four boxes in square | PMM UI - QAN | |
| Left arrow | PMM UI | |
| 3 horizontal lines | PMM UI - HA dashboards | |
| Bell | PMM UI - Alerting | |
| Lightening flash/bolt | PMM UI - Nodes compare | |
| Right caret | General | |
| Clock (at nine) | PMM UI - Time range selector | |
| Cog wheel | PMM UI Configuration | |
| Share comment symbol | PMM UI - Share dashboard image | |
| Compass | PMM UI - Explore | |
| Copy | PMM UI - Copy (e.g. backup schedule) | |
| Cube | PMM UI | |
| Database | PMM UI DBaaS symbol | |
| Vertical ellipsis | PMM UI column menus | |
| Exclamation mark in triangle | PMM UI - Warnings | |
| Eye with slash | PMM UI Password hide | |
| Eye | PMM UI Password reveal | |
| File symbol | PMM UI - Home dashboard | |
| 3-bar chart | PMM UI link to dashboard | |
| Backward arrow circle around clock | PMM UI - Backups and checks | |
| List | PMM UI - Alert rules | |
| Computer monitor | PMM UI - Cycle view mode | |
| Pen | PMM UI - Edit | |
| Plus within circle | PMM UI Inventory->Add Instance | |
| Plus within square | PMM UI - Add | |
| Question mark in circle | PMM UI - Help | |
| Minus in magnifying glass | PMM UI - Time range zoom out | |
| Magnifying glass | PMM UI - Search | |
| Cog wheel | PMM UI Configuration->Settings | |
| Share symbol | PMM UI - Share dashboard | |
| Shield | PMM UI - Server admin | |
| Star | PMM UI - Dashboard favourites | |
| Twin backward arrows | PMM UI - Refresh dashboard | |
| Hand, thumbs down | For Benefits/Drawbacks tables | |
| Hand, thumbs up | For Benefits/Drawbacks tables | |
| Large 'X' | PMM UI | |
| Toggle (off) | PMM UI - Toggle switch | |
| Toggle (on) | PMM UI - Toggle switch | |
| Trash can | PMM UI - Various 'Delete' operation |
Custom (in-house design) icons are defined as SVG code in variables.yml.
| Usage | Description | Used where |
|---|---|---|
{{icon.addinstance}} |
Thin + in circle | PMM Add Instance |
{{icon.checks}} |
Checkbox list items | Inventory list |
{{icon.inventory}} |
Checkbox list items | PMM Inventory & Inventory List |
{{icon.dashboards}} |
Abstract blocks assembly | PMM Dashboards |
{{icon.node}} |
Circle surrounded by smaller circles | Node dashboards |
{{icon.percona}} |
Percona logo | Wherever PMM home icon is needed |
While MkDocs will automatically replace certain strings with symbols, it's preferable where possible to use unicode symbols for other icons, so that they appear when the raw Markdown is exported as HTML and imported into Google Docs.
| For | Use |
|---|---|
| --> | → |
We have attempted to eschew traditional terminology used in software manuals. Some examples:
- "Setting up" instead of "installation and configuration"
- "Before you start" instead of "Prerequisites"
There are no "introduction" or "overview" sections. These texts are just there under the title.
Section titles are deliberately short. For example, in Setting up/Server/Docker, the 'Run' section shows how to run the docker image for PMM Server. The docs are for 'PMM', the section is 'Server' and subsection 'Docker'. That's what we're running.
Most Markdown processors automatically number lists when they are like this:
1. Item
1. Item
1. Item
...But to make the raw Markdown easier to read, we recommend explicitly numbering items:
1. Item
2. Item
3. Item
...Other advantages:
- contents can be reused in source code comments by developers;
- encourages authors to pay attention to the order and number of steps in a recipe.