Markdown & MDX Constructs

Intuition

The language of documentation: Markdown is like a simplified HTML — it uses plain text formatting that humans can read and write efficiently, while computers can convert it to beautiful rendered pages. It is the lingua franca of technical documentation.

Why it matters: Markdown is everywhere — GitHub READMEs, documentation sites, blog posts, even Jupyter notebooks. Mastering it lets you create professional-looking documentation without fighting with WYSIWYG editors.

The key insight: Use headings consistently (never skip levels), code blocks for all code, and tables for structured data — these conventions make your docs scannable and prevent rendering issues across platforms.

Standard Markdown

Headings

Use # through ######. Do not skip levels (e.g., jumping from ## to ####). The first heading In a page body should be ## because Docusaurus uses the frontmatter title as the h1.

## Level 2

### Level 3

#### Level 4

Emphasis

_italic_ or _italic_ **bold** or **bold** **_bold italic_** ~~strikethrough~~

Links and Images

[link text](https://example.com) [reference link][ref]

[ref]: https://example.com

![alt text](image.png)

For images stored in the same docs directory, use relative paths. Docusaurus resolves them at build Time and copies them to the static output.

Blockquotes

> This is a blockquote.
>
> It can span multiple paragraphs.

Nesting is supported:

> Level 1
>
> > Level 2

Lists

Unordered:

- Item
- Item
  - Nested item
  - Another nested item

Ordered:

1. First
2. Second
3. Third
   1. Nested

Horizontal Rule

---

<!-- Breadcrumb Schema for SEO -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [{"name": "Home", "url": "https://wyattau.com"}, {"name": "tools", "url": "https://tools.wyattau.com"}, {"name": "General", "url": "https://tools.wyattau.com/general"}, {"name": "Markdown Constructs", "url": "https://tools.wyattau.com/general/markdown-constructs"}]
}
</script>

Three or more hyphens, asterisks, or underscores on a line by themselves.

Extended Markdown Features (GFM)

Tables

| Header 1   | Header 2 | Header 3    |
| ---------- | -------- | ----------- |
| Cell 1     | Cell 2   | Cell 3      |
| Left align | Center   | Right align |
| Left align | Center   | Right align |

Column alignment with colons:

| Left | Center | Right |
| :--- | :----: | ----: |
| L    |   C    |     R |

Tables that need complex cell content (code blocks, lists) will not render correctly in standard Markdown. For those cases, use the custom .grid-table CSS class with div-based structure, or use An MDX component.

Task Lists

- [x] Completed task
- [ ] Incomplete task
- [ ] Another incomplete task

These render as checkboxes. Useful for tracking progress in notes.

Footnotes

Here is a statement that needs a citation[^1].

[^1]: This is the footnote content. It appears at the bottom of the page.

Footnotes support multiple references to the same note and can contain inline formatting, links, and Even code.

Definition Lists

Some markdown processors support definition lists, but they are not part of standard GFM. In Docusaurus, use a description list via HTML or a custom component if needed.

Strikethrough

~~This text is struck through.~~

Renders as ~~This text is struck through.~~

Code Blocks

Inline Code

`Backticks` for inline code. For template syntax or generics, escape angle brackets outside Code blocks: use std::vector<int> in prose.

Fenced Code Blocks

Specify the language after the opening fence for syntax highlighting:

```python
Def hello():
 print("Hello, world")
```

```cpp
#include <iostream>

Int main() {
 std::cout << "Hello, world\n";
}
```

Supported languages include python``cpp``java``dart``javascript``typescript``bash json``yaml``sqlAnd many more.

Line Highlighting

Docusaurus supports commenting specific lines to highlight them:

```python
Def greet(name): # highlight-next-line
 print(f"Hello, {name}")
 return True # highlight-line
```

Custom Title

```python title="my_script.py"
Print("hello")
```

Diff Mode

```diff
- old line
+ new line
 unchanged line
```

Docusaurus-Specific MDX Features

Admonitions

Admonitions are the preferred way to call out important information:

<aside class="starlight-aside starlight-aside--note">
> **Tip:** This is a tip.

> **Info:** This is informational.

> **Caution:** This is a caution.

> **Danger:** This is dangerous.

> **Caution:** This is a warning.

Admonitions support optional titles:

> **Tip:** Custom Title Content here.

They can also be collapsible (Docusaurus 3):

:::note[Click to expand] Hidden content that is revealed on click.
</aside>

Tabs

Tabs require an MDX import:

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

&lt;Tabs&gt; &lt;TabItem value="python" label="Python"&gt;

```python
Print("Python code")
```

&lt;/TabItem&gt; &lt;TabItem value="java" label="Java"&gt;

```java
System.out.println("Java code");
```

&lt;/TabItem&gt; &lt;/Tabs&gt;

Tabs support synchronization by groupId. Tabs with the same groupId across the page will switch In unison:

&lt;Tabs groupId="language"&gt; &lt;TabItem value="python" label="Python"&gt; ... &lt;/TabItem&gt;
&lt;TabItem value="java" label="Java"&gt; ... &lt;/TabItem&gt; &lt;/Tabs&gt;

Math with KaTeX

This site imports KaTeX CSS in src/css/custom.css. Use it for mathematical notation.

Inline math:

The quadratic formula is $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$.

Block math:

$$
\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi}
$$

KaTeX supports a wide range of LaTeX commands. Refer to the KaTeX supported functions list for what is available.

Mermaid Diagrams

Docusaurus supports Mermaid diagrams natively in code blocks:

```mermaid
Graph TD
 A[Start] --> B{Decision}
 B -->|Yes| C[Action 1]
 B -->|No| D[Action 2]
 C --> E[End]
 D --> E
```

Supported diagram types include graph``sequenceDiagram``classDiagram``stateDiagram erDiagram``gantt``pieAnd flowchart.

This site adds a hover zoom effect on Mermaid SVGs via src/css/custom.css:

.mermaid svg:hover {
  transform: scale(1.2);
  transform-origin: center;
}

Details / Summary

&lt;details&gt; &lt;summary&gt;Click to expand&lt;/summary&gt;

Hidden content here.

&lt;/details&gt;

### MDX Import Statements

Since Docusaurus processes .md files as MDX, you can import React components:

import CodeBlock from '@theme/CodeBlock';
import { Tabs } from '@astrojs/starlight/components';
import { TabItem } from '@astrojs/starlight/components';
import BrowserOnly from '@docusaurus/BrowserOnly';

;

Common @theme imports:

Component	Purpose
`CodeBlock`	Render a code block from a file path
`Tabs` / `TabItem`	Tabbed content switching
`Details`	Collapsible sections with React state
`Admonition`	Programmatic admonition rendering
`Head`	Inject elements into `<head>`

Custom components from @site/src/components/ are also importable:

import MyComponent from '@components/MyComponent';

&lt;MyComponent prop="value" /&gt;

Frontmatter Options

Every page should have frontmatter. Here is the full set of commonly used fields:

---

<!-- Breadcrumb Schema for SEO -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [{"name": "Home", "url": "https://wyattau.com"}, {"name": "tools", "url": "https://tools.wyattau.com"}, {"name": "General", "url": "https://tools.wyattau.com/general"}, {"name": "Markdown Constructs", "url": "https://tools.wyattau.com/general/markdown-constructs"}]
}
</script>
id: my-page # URL path segment (overrides filename)
title: My Page Title # Display title and h1
description: 'Use through . Do not skip levels (e.g., jumping from to ). The first heading In a page body should be because Docusaurus uses the frontmatter as the .'
slug: /custom/url/path # Full URL override
title: Short Name # Override display name in sidebar
date: 2025-05-15T22:45:51Z
tags:
  - tag1
  - tag2
categories:
  - category1
image: /img/thumbnail.png # Social sharing image
hide_table_of_contents: false
toc_max_heading_level: 4 # Max heading level for ToC
draft: true # Hide from production build
---

<!-- Breadcrumb Schema for SEO -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [{"name": "Home", "url": "https://wyattau.com"}, {"name": "tools", "url": "https://tools.wyattau.com"}, {"name": "General", "url": "https://tools.wyattau.com/general"}, {"name": "Markdown Constructs", "url": "https://tools.wyattau.com/general/markdown-constructs"}]
}
</script>

Slug Behavior

Without slug: derived from file path, e.g., docs/docs_general-notes/intro.md becomes /docs/general-notes/intro.
With slug: custom-slug: becomes /docs/custom-slug.
With slug: /absolute/path: becomes /absolute/path (bypasses the docs prefix).

Tags and Categories

Tags and categories populate the blog-like tag pages and aid search. They are flat strings — no Hierarchy. Use lowercase, hyphen-separated values for consistency:

tags:
  - c-plus-plus
  - concurrency
  - modern-cpp

Escaping Rules for MDX

Since MDX treats angle brackets as JSX, bare < and > in prose cause build errors.

In Prose

Write std::vector<int> instead of std::vector<int>.

In Tables

Same rule applies inside table cells:

| Type                   | Description           |
| ---------------------- | --------------------- |
| `std::vector&lt;T&gt;` | Dynamic array         |
| `std::map&lt;K, V&gt;` | Associative container |

In Code Blocks

No escaping needed inside fenced code blocks — the content is treated as raw text.

Raw HTML Restrictions

Do not use “tags or other raw HTML block elements. MDX does not allow them. Use markdown or Docusaurus components instead. Self-closing elements like<br />and<img /> are generally fine.

Common Pitfalls

Focusing only on content knowledge without developing exam technique and question-answering skills.
Ignoring feedback from marked work and failing to address recurring weaknesses.
Not making connections between different topics within the subject to build a coherent understanding.
Memorising content without understanding the underlying principles. This leads to poor application in unfamiliar contexts.

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.

Common Pitfalls in Markdown and MDX

Pitfall	Symptom	Fix
Nested blockquotes	Incorrect nesting breaks rendering	Use `>` for level 1, `> >` for level 2
Table alignment markers	Misaligned columns in rendered output	Ensure colons line up with hyphens in separator row
Inline code with pipes	Pipe breaks table structure	Use backtick-escaped code: \`code\`
Task list checkboxes	Checkboxes not rendering as interactive	Use `- [x]` and `- [ ]` with spaces exactly as shown
Unescaped angle brackets	Build error in MDX files	Write `<` and `>` in prose and table cells
Missing language on code fence	No syntax highlighting applied	Always specify language: ```python
Incorrect admonition syntax	Admonition rendered as blockquote	Use `:::note` at start, `:::` at end on its own line
Double blank lines	Unnecessary vertical space in output	Use single blank lines between sections
Tabs vs. spaces in code blocks	Indentation rendered inconsistently	Use consistent indentation (2 or 4 spaces) throughout
Frontmatter title as h1	Duplicate h1 heading in rendered page	Start body content with `##` (h2) level headings

Cross-References

Testing: Markdown Constructs: Interactive testing of Markdown constructs and formatting.
Alleviate Back Pain: Example page demonstrating Markdown formatting in practice.
Crafting Ghee: Another example page with MDX components and formatting.

Mark this page as reviewed