Formatting toolkit¶
Each snippet is followed by what it produces on the wiki. (On GitHub you only see the raw text.)
Which one do I use?
| Your content | Use |
|---|---|
| A list of items, each with a paragraph or more of explanation, all relevant to every reader | ??? numlist / ??? deflist |
| Steps done in order, each with an explanation | ???+ steps |
| Steps done in order, written as plain sentences or always visible (emergencies) | <div class="steps-list" markdown> around a numbered list |
| Items with a one-line explanation | a plain bullet list — there is nothing worth hiding |
| The reader needs exactly one of several alternatives (Windows/macOS, one of three procedures) | content tabs (=== "Tab") |
| A single aside, warning or tip interrupting the text | !!! warning, !!! tip, … |
| Troubleshooting entries the reader consults only when something breaks | ??? failure "Symptom" |
| Points with no order, or steps short enough to need no line | a plain bullet or numbered list (styled automatically) |
| The main places a reader can go from an index page | grid cards (<div class="grid cards" markdown>) |
| One action: download a file, open an external site | a button ({ .md-button }) |
| Code lines that need a short explanation | code notes (# (1)! and a numbered list under the code) |
| An icon or small screenshot that should not open large | { .off-glb } after the image |
| Stimulus sizes in degrees, millimetres and pixels for a lab screen | the visual angle calculator |
A run of three or more !!! boxes in a row is a sign that none of them is
really an aside, and that the section wants one of the list forms above.
Lists¶
Bullets and numbered lists¶
Plain Markdown lists get the wiki style on their own. Each level down is a little lighter (darker in dark mode).
- A point
- A detail
- A finer detail
- A detail
- First
- Second
- A sub-step
- A sub-sub-step
- A sub-step
Steps in order¶
The numbers get a connecting line.
- Book the room.
- Prepare the participant.
Collapsible lists¶
Each term opens to show its explanation: ??? starts closed, ???+ starts open. Numbers restart at every heading. More in Collapsible definition lists.
??? deflist "Laptop (bullet, closed)"
Bring your own, with MATLAB installed.
???+ deflist "Charger (bullet, open)"
The lab has no spare one.
Laptop (bullet, closed)
Bring your own, with MATLAB installed.
Charger (bullet, open)
The lab has no spare one.
??? numlist "Ethics application (numbered, closed)"
Submit it before recruiting.
???+ numlist "Data management plan (numbered, open)"
Write it with the RDM team.
Ethics application (numbered, closed)
Submit it before recruiting.
Data management plan (numbered, open)
Write it with the RDM team.
???+ steps "Book the room (step, open)"
Use the online calendar.
??? steps "Run the session (step, closed)"
Follow the checklist.
Book the room (step, open)
Use the online calendar.
Run the session (step, closed)
Follow the checklist.
Checklists¶
- Consent form signed
- Data uploaded
Terms and definitions¶
- Sampling rate
- How many samples per second the amplifier records.
Boxes¶
Callouts¶
Types: note, abstract, info, tip, success, question, warning, failure, danger, bug, example, quote.
Good to know
Shown in a box.
Warning
Without a title, the box shows its type.
Collapsible callouts¶
??? starts closed, ???+ starts open. Any type works.
??? info "More details (closed)"
Hidden until clicked.
???+ example "An example (open)"
Shown, and can be closed.
More details (closed)
Hidden until clicked.
An example (open)
Shown, and can be closed.
Do and don't¶
<div class="do-list" markdown>
<p class="do-list__heading">Do</p>
- Check the screening form.
</div>
<div class="dont-list" markdown>
<p class="do-list__heading">Don't</p>
- Start without a signed form.
</div>
Do
- Check the screening form.
Don't
- Start without a signed form.
Emergency card¶
One per page, for the number to call.
<div class="care-card care-card--emergency" markdown>
<p class="care-card__heading">Emergency: call 112</p>
<div class="care-card__body" markdown>
Say what happened and where you are.
</div>
</div>
Emergency: call 112
Say what happened and where you are.
Layout¶
Tabs¶
Tabs with the same names switch together across the page.
Steps for Windows.
Steps for macOS.
Cards¶
As many per row as fit, each about square.
<div class="grid cards" markdown>
- :material-school:{ .lg .middle } __Learn the basics__
---
One sentence on what the reader finds there.
[Start here](#cards)
- :material-clipboard-text:{ .lg .middle } __Plan a study__
---
One sentence on what the reader finds there.
[Start here](#cards)
</div>
-
Learn the basics
One sentence on what the reader finds there.
-
Plan a study
One sentence on what the reader finds there.
Model and tool cards¶
A card per model, tool or dataset, in groups with a colour: classic, brain, language or topo. The part above the line shows when the card is closed; add open to <details to show it open.
#### Brain-inspired models { .resource-group .resource-group--brain }
<details class="resource-card resource-card--brain" markdown>
<summary markdown="block">
#### VOneNet
[:material-file-document-outline: Paper](https://proceedings.neurips.cc/paper/2020/hash/98b17f068d5d9b7668e19fb8ae470841-Abstract.html) [:material-github: Code](https://github.com/dicarlolab/vonenet)
{ .resource-card__links }
**Pick it when** you want a model of primate V1 in front of a standard CNN.
</summary>
Architecture
: Fixed V1 model + ResNet-50
Trained on
: ImageNet
{ .resource-card__figure }
{ .resource-card__plate }
What the panels show, in one or two sentences.
{ .resource-card__caption }
</details>
Brain-inspired models¶
VOneNet¶
Pick it when you want a model of primate V1 in front of a standard CNN.
- Architecture
- Fixed V1 model + ResNet-50
- Trained on
- ImageNet
What the panels show, in one or two sentences.
Two columns¶
Side by side on wide screens, one under the other on phones.
Left: text, a list or an image.
Right: the same.
Buttons¶
[:material-download: Download the kit](#buttons){ .md-button }
[Open the form](#buttons){ .md-button .md-button--primary }
Download the kit Open the form
Tables¶
Striped rows, with the header kept in view.
| Room | Equipment |
|---|---|
| PSI 00.57 | TMS |
| PSI 00.52 | EEG |
Visual angle calculator¶
Converts stimulus sizes between degrees, millimetres and pixels for one lab set-up, with a drawing of the screen. data-setup picks the set-up: mr11 (MR11 BOLDscreen) or eeg (EEG booth). Each set-up's values live once, in SETUPS at the top of docs/javascripts/visual-angle.js; add a set-up there and keep it in step with the screen table on its page.
<div class="va-calc" data-setup="eeg">
<p>Turn on JavaScript to use the visual angle calculator.</p>
</div>
Turn on JavaScript to use the visual angle calculator.
The text around it is shared too: the steps to check visual angles, the line that introduces the calculator and the PsychoPy note are sections of includes/visual-angles.md. A page pulls in each section by name and adds only what belongs to its set-up (the viewing distance step, its own numbers):
<div class="steps-list" markdown>
--8<-- "includes/visual-angles.md:check-screen"
2. **Viewing distance.** How to measure it in this room.
--8<-- "includes/visual-angles.md:check-script"
</div>
--8<-- "includes/visual-angles.md:calculator"
Images¶
Images¶
Every image opens large on click, with a zoom bar.
 <!-- opens large on click -->
{ .off-glb } <!-- stays small: icons, buttons -->
{ .img-border } <!-- thin border -->
Figure with a caption¶
<figure markdown="span">
{ width="420" }
<figcaption>A caption under the image.</figcaption>
</figure>
Text¶
Inline formatting¶
Press ++ctrl+c++ to copy. Mark ==important words==, ^^inserted text^^ and ~~removed text~~.
H~2~O and x^2^. A footnote[^1], an icon :material-brain:, and math: $E = mc^2$.
[^1]: The footnote text, shown at the bottom of the page.
Press Ctrl+C to copy. Mark important words, inserted text and removed text.
H2O and x2. A footnote1, an icon , and math: \(E = mc^2\).
Progress bar¶
Code¶
Code blocks¶
Every code block gets a copy button. Add a title and highlight lines:
```python title="analysis.py" hl_lines="2"
data = load("sub-01")
clean = filter(data)
```
Inline code with colour: `#!python print("hello")`.
Inline code with colour: print("hello").
Code with numbered notes¶
- A note that opens from the number in the code.
Shared and hidden text¶
The same text on several pages¶
Write it once in includes/ and pull it into each page with one line:
Open tasks on a page¶
Hidden notes that open a GitHub issue for the page: see Adding tags.
Your name under each page¶
Every page lists the people who wrote it. If yours shows a GitHub handle, or twice, add a line to .mailmap:
Collapsible definition lists¶
When a section is a list of things that each need a short explanation — the
documents an application must contain, the tools on a machine, the fields in a
form — use ??? numlist (numbered) or ??? deflist (bulleted) instead of a run
of !!! boxes. The term stays visible so the whole list can be scanned at a
glance, and the explanation opens on click:
??? numlist "Accompanying letter signed by the PI"
You can find the guidelines [here](https://example.org).
???+ numlist "Research protocol, including a summary in Dutch"
Best to follow the CTC template, which already covers safety procedures.
???starts closed,???+starts open.- Indent the body by four spaces, exactly like an admonition.
- Numbering is automatic and restarts at every heading, so you can reorder or insert entries without renumbering anything by hand.
- Each entry gets its own anchor from its term, so you can link straight to it:
[the ICF requirements](MEC.md#informed-consent-forms-icfs). Opening such a link expands that entry. If the term is the same as a heading or another entry on the page,-2,-3, … is appended to keep the anchor unique. Everything also expands automatically when the page is printed or saved as PDF.
Which renders as:
Accompanying letter signed by the PI
You can find the guidelines here.
Research protocol, including a summary in Dutch
Best to follow the CTC template, which already covers safety procedures.
Informed consent forms, in English and in Dutch
The templates already carry the legal basis for data processing. Three parts:
- essential information to decide on participation
- the consent form
- any appendices
For steps that follow each other in order (a procedure, the path to a first session), use ??? steps. It looks
exactly like ??? numlist, and a vertical line joins the numbers so the steps read as one sequence. Write ???+ steps
to show every step open:
???+ steps "Get ethical approval"
Submit the study to the ethics committee.
???+ steps "Book the room"
Book it in Calira once approval is in.
The line runs only between consecutive steps entries, so a paragraph or heading between two entries ends the
sequence. Numbering restarts at every heading, as for numlist.
For a procedure whose steps are plain sentences, or one that must stay visible without clicking (an emergency), wrap an ordinary numbered list in a
steps-list block. It draws the same circles and line:
Safety guidance: care cards and do / don't lists¶
For safety and emergency information, two blocks follow the NHS design system
(care cards,
do and don't lists).
Use them sparingly: one emergency card per page, for the number to call. For other warnings, use the usual !!! danger or !!! warning boxes.
<div class="care-card care-card--emergency" markdown>
<p class="care-card__heading">Emergency: call +32 16 32 22 22</p>
<div class="care-card__body" markdown>
What to say and where you are.
</div>
</div>
<div class="dont-list" markdown>
<p class="do-list__heading">Don't</p>
- Never get the TMS coil wet.
</div>
do-list gives green ticks, dont-list red crosses.
-
The footnote text, shown at the bottom of the page. ↩