Skip to content

Markdown Constructs

Intuition

The building blocks of documentation: Markdown constructs are like LEGO bricks for documentation — each construct (headings, tables, code blocks, asides) serves a specific purpose, and combining them effectively creates clear, scannable, and maintainable content.

Why it matters: Good documentation is read, not just written. Using consistent markdown constructs ensures your docs render correctly across platforms, are accessible to screen readers, and remain maintainable as content grows.

The key insight: Use asides for supplementary information that would interrupt the flow of the main text — they let you add warnings, tips, and notes without breaking the reading experience.

Remark Common Plugins

Remark Grid Table

Usage of root remark-grid-table Is discouraged with Docusaurus, use Adobe remark-gridtables instead. Remark Grid tables Seems to be broken at the moment, the following does not seem to work:

+----+----+
| A  | B  |
+----+----+
| 1  | 2  |
+----+----+
+-------------------+------+
| Table Headings    | Here |
+--------+----------+------+
| Sub    | Headings | Too  |
+========+=================+
| cell   | column spanning |
| spans  +---------:+------+
| rows   |   normal | cell |
+---v----+:---------------:+
|        | cells can be    |
| --- | --- | --- |
|        | *formatted*     |
|        | **paragraphs**  |
|        | ```             |
| multi  | and contain     |
| line   | blocks          |
| cells  | ```             |
+========+=========:+======+
| footer |    cells |      |
+--------+----------+------+

Code Snippets

Math

Using remark math with rehype Katex, equations written in LaTeX can be rendered, however LaTeX Packages cannot be included.

{∂ρ}{∂t}+{∂(ρu{i})}{∂x{i}}=0\frac\{\partial \rho\}\{\partial t\} + \frac\{\partial(\rho u_\{i\})\}\{\partial x_\{i\}\} = 0

Admonitions

Docusaurus supports admonition callouts using triple-colon syntax:

<aside class="starlight-aside starlight-aside--note">
<strong>Note</strong>
This is a note block.
</aside>
> **Tip:** This is a tip block.
> **Caution:** This is a warning block.
<aside class="starlight-aside starlight-aside--danger">
<strong>Danger</strong>
This is a danger block.
</aside>

Custom titles are supported: :::info[Custom Title]

Tables

Standard markdown tables use pipe-delimited rows with a header separator:

FeatureSupportedNotes
BasicYesPipe-delimited with --- separator
AlignmentYes:---, :---:, ---: for left/center/right
ColspanNoNot supported in standard markdown; use HTML

Nested Lists and Checklists

1. First item
   - Sub-item with a nested point
     - Further nesting
2. Second item
   - [ ] Unfinished task
   - [x] Completed task

Mermaid Diagrams

Docusaurus renders Mermaid diagrams inside fenced code blocks tagged with mermaid:

```mermaid
graph TD
    A[Start] --> B\{Decision\}
    B -->|Yes| C[Action A]
    B -->|No| D[Action B]
```

Supported diagram types include flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, pie charts, and git graphs.

Details / Collapsible Sections

<details>
  <summary>Click to expand</summary>
  Hidden content here.
</details>

Tabs Component

The tabs UI is provided via Docusaurus theme imports:

import { Tabs, TabItem } from "@astrojs/starlight/components";

<Tabs>
  <TabItem label="Option A">Content for A</TabItem>
  <TabItem label="Option B">Content for B</TabItem>
</Tabs>

Group tabs across the page with a shared groupId prop.

Inline HTML

Docusaurus allows raw HTML when markdown constructs are insufficient. Common uses include styled <div> containers, <iframe> embeds, and <details> elements. Keep HTML usage minimal to maintain portability across renderers.

Common Pitfalls

  1. Memorising content without understanding the underlying principles. This leads to poor application in unfamiliar contexts.

  2. Focusing only on content knowledge without developing exam technique and question-answering skills.

  3. Not practising with past papers or exercises under timed conditions.

  4. Ignoring feedback from marked work and failing to address recurring weaknesses.

Additional Math Examples

Inline math: E=mc2E = mc^2 and ∇×E=−∂B∂t\nabla \times \mathbf{E} = -\frac{\partial \mathbf{B}}{\partial t}.

Block math with aligned equations:

∇⋅E=ρε0∇⋅B=0\begin{aligned} \nabla \cdot \mathbf{E} &= \frac{\rho}{\varepsilon_0} \\ \nabla \cdot \mathbf{B} &= 0 \end{aligned}

Summary

The key principles covered in this topic are linked in the sub-pages above. Focus on understanding the definitions, applying the formulas or frameworks, and evaluating strengths and limitations of each approach.

Worked Examples

Worked examples demonstrating the application of key concepts are covered in the detailed sub-pages linked above.

Cross-References