Page components¶
Everything on this page is enabled in mkdocs.yml and available on any page in docs/.
Each section gives the Markdown, the result, and the case the component is for. The
style guide governs what goes inside them.
Two of these are local to this site — the console and cli box types, and the filter
box. The rest are Material for MkDocs
features.
Admonitions¶
An admonition is a box that interrupts the reading order. Its type sets the colour and the icon; its title states the fact inside it, not a label for it.
!!! warning "Removing the startup probe restarts the pod during model load"
A 30 GB model takes longer to load than the default liveness timeout allows.
Removing the startup probe restarts the pod during model load
A 30 GB model takes longer to load than the default liveness timeout allows.
Five types are in use here. The others Material provides are available but unused, and a sixth colour on a page is a colour nobody has learned.
| Type | Colour | For |
|---|---|---|
note |
Blue | Context the reader can skip |
tip |
Teal | A better way to do what they are already doing |
warning |
Orange | Something that will cost them time or data if ignored |
console |
Green | The same operation in the web console |
cli |
Slate | The same operation with oc |
console and cli exist because every subject in this repository is documented twice,
once as a form and once as a manifest. The pair of colours says which one a box belongs to
before the title is read:
The Applied column, not the object, is what says the database exists
WebHosting > Databases > PostgreSQL lists the objects. A row can be present while the cluster has not applied it yet.
oc get databases is ambiguous in a project running both engines
MariaDB installs a Database kind too. Use the fully qualified
databases.postgresql.cnpg.io.
Collapsible boxes¶
Three question marks instead of three exclamation marks make the same box collapsible.
Add + to have it start open.
Recreate the manifest this form produces
Use one for something a subset of readers needs and the rest should not have to scroll past: the long form of a step, the manifest a form generates, a failure that only affects one distribution.
A warning behind a click is a warning nobody read
Anything the reader must not miss stays open. Collapsing is for depth, not for tidiness.
Code annotations¶
A (1)! comment in a code block becomes a numbered marker; the list under the block
becomes the text that marker opens. The annotation lands next to the line it describes,
which prose under the block cannot do.
```yaml title="values.yaml"
bifrost:
authConfig:
existingSecret: gateway-auth-secret # (1)!
usernameKey: username
```
1. The Secret is read at start-up. Changing it needs a restart.
- The Secret is read at start-up. Changing it needs a restart.
The marker goes inside a comment for the language of the block — # (1)! in YAML, shell
and Python, // (1)! in Go and TypeScript — so the block stays valid if it is copied.
Content tabs¶
For one operation with several equally valid forms. Not for a sequence: three tabs are three alternatives, and a reader who has to open all three is reading steps.
=== "macOS"
```bash
brew install openshift-cli
```
=== "Linux"
```bash
curl -L https://.../oc.tar.gz | tar xz
```
Tabs with the same label are linked across the whole site. A reader who picks macOS
here has it selected on every other page, so the label has to be the thing being chosen —
macOS, Python, oc — and not a description of the tab's contents.
Filter box¶
A search field over a table that is already on the page. The site search answers which page; this answers which of these twenty rows, which is the question an index page gets asked.
<div class="grn-filter" data-filter-noun="guides" data-filter-placeholder="postgres, virtual key" markdown>
| Guide | Area | What you get |
| --- | --- | --- |
| ... | ... | ... |
</div>
| Attribute | Effect |
|---|---|
data-filter-noun |
Plural noun in the resting count — 21 guides |
data-filter-placeholder |
Replaces the generated placeholder |
markdown |
Required, or Markdown inside the div is not parsed |
Words are ANDed and matched anywhere in the row, so redis cache finds a row containing
both. The guides index is the working example.
It is inserted by docs/javascripts/filter.js after the page loads, over a table that is
complete without it. A reader with no JavaScript, and anything reading
llms.txt, still gets the whole table.
Use one on a table of at least ten rows that a reader arrives at looking for a specific one. A table that is read top to bottom does not need it.
The same box, collapsed
A filter inside a collapsible box focuses the field when the box opens.
| Command | What it answers |
|---|---|
oc get events -n <project> --sort-by=.lastTimestamp |
What has the cluster done recently |
oc describe pod <pod> -n <project> |
Why is this pod not running |
oc logs <pod> -n <project> --previous |
Why did the last instance exit |
oc describe quota -n <project> |
Is the project out of quota |
oc adm top pod -n <project> |
What is this pod using |
Screenshots¶
A console capture is taken at panel width and drawn into a 688-pixel column, which is below
the size at which form labels stay readable. Every content image is clickable and opens at
full size; { .no-lightbox } opts one out.
/// caption under an image produces a real figure and figcaption pair, so the
description sits with the image rather than reading as the next paragraph:
/// caption
The cluster picker defaults to the project's existing cluster.
///
Alt text and caption do different jobs. Alt text describes the image for a reader who cannot see it; the caption says what to look at. Write both, and do not repeat one in the other.
Abbreviations¶
An acronym defined in includes/abbreviations.md becomes a tooltip wherever it appears,
on every page, with no markup on the page itself. PVC, RBAC and CNPG in this sentence are
all coming from that file.
Two rules for adding one, both in the comment at the top of the file: only an acronym a reader might not know, and never the subject of the page it appears on. Defining API or TLS would put a dotted underline under half the site.
Highlighting¶
==text== marks a span. It is for the one line in a block that the reader is being told to
change, and it uses the same colour as a filter hit, so the two mean the same thing.
Set replicas: 3 before applying this to production.
Keyboard keys¶
++ctrl+c++ renders as Ctrl+C. Use it for keys the reader presses, not for a value
they type.