Markdown Style Guide

This page documents every Markdown and MDX element supported in writings — useful for checking how things render before publishing, and for verifying styles after theme changes.

Headings

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

Paragraph

A paragraph is one or more consecutive lines of text separated by a blank line. It wraps naturally at the content width and maintains comfortable line lengths for reading.

This is a second paragraph. Notice how the spacing above creates a clear visual break between them. Line height and measure are the two most impactful typographic decisions — both are set in the global styles.

Emphasis

This is bold text, italic text, and strikethrough. You can also combine bold and italic together.

1
This is **bold text**, _italic text_, and ~~strikethrough~~.
2

3
You can also combine **_bold and italic_** together.

Blockquote

The details are not the details. They make the design.

~ Charles Eames

Nested blockquotes are supported.

This is a nested blockquote inside the outer one.

1
> The details are not the details. They make the design.
2
>
3
> ~ <cite>Charles Eames</cite>
4

5
> Nested blockquotes are supported.
6
>
7
> > This is a nested blockquote inside the outer one.

Links

Internal links use the site’s base path. External links automatically open in a new tab.

Back to writings — internal link

Astro documentation — external link, opens in new tab

1
[Back to writings](/kanso/writing/)
2

3
[Astro documentation](https://docs.astro.build)

Footnotes

An example containing a clickable footnote reference¹ with a return link.

A second reference² demonstrating multiple footnotes on the same page.

1
An example containing a clickable footnote reference[^1].
2

3
[^1]: First footnote — includes a return link.

Image

A standalone Markdown image, unwrapped from its paragraph container:

1
![Placeholder image — 720×400](https://placehold.co/720x400)

The Image MDX component supports captions and additional layout options:

1
import Image from "@/components/Image.astro";
2

3
<Image
4
  src="https://placehold.co/720x400"
5
  alt="Placeholder image with caption"
6
  caption="Figure 1. A placeholder image rendered via the Image component."
7
  inferSize
8
/>

Table

A simple table with default left-aligned columns:

A wider table to test horizontal scrolling on small screens — columns use alignment syntax:

1
| Property | Type      | Default | Required |
2
| -------- | --------- | ------- | -------- |
3
| title    | `string`  | —       | Yes      |
4
| draft    | `boolean` | `false` | No       |

Code

Inline code uses a monospace font with a subtle background.

A TypeScript block with syntax highlighting:

1
import { getCollection, type CollectionEntry } from "astro:content";
2

3
export async function getPublishedWritings(): Promise<CollectionEntry<"writing">[]> {
4
  return getCollection("writing", w => !w.data.draft);
5
}

A CSS block with a filename label:

1
:root {
2
  --color-bg: var(--color-surface-100);
3
  --color-text: var(--color-surface-900);
4
  --font-body: "PT Serif", Georgia, serif;
5
  --font-display: "Lora", Georgia, serif;
6
}
7

8
@media (prefers-color-scheme: dark) {
9
  :root {
10
    --color-bg: var(--color-surface-900);
11
    --color-text: var(--color-surface-100);
12
  }
13
}

A shell block:

1
npm run dev       # start dev server at localhost:4321
2
npm run build     # astro check + astro build + pagefind
3
npm run lighthouse -- --build

Lists

Ordered list

1. First item
2. Second item
3. Third item
   1. Nested first
   2. Nested second

1
1. First item
2
2. Second item
3
3. Third item
4
   1. Nested first
5
   2. Nested second

Unordered list

• List item one
• List item two
• List item three
  • Nested item
  • Another nested item

1
- List item one
2
- List item two
3
  - Nested item

Task list

• Schema defined in src/content.config.ts
• Sample writings added
• Replace placeholder content with real data
• Accessibility audit

1
- [x] Completed task
2
- [ ] Incomplete task

Other Elements

Abbreviation

The HTML specification is maintained by the W3C. Hover the abbreviation to see its expansion.

1
The <abbr title="HyperText Markup Language">HTML</abbr> specification
2
is maintained by the <abbr title="World Wide Web Consortium">W3C</abbr>.

Subscript and Superscript

H₂O is water. X² is X squared. The chemical formula for caffeine is C₈H₁₀N₄O₂.

1
H<sub>2</sub>O and X<sup>2</sup>

Keyboard

Press Cmd + Shift + P to open the command palette. Press Esc to close.

1
Press <kbd>Cmd</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd> to open the command palette.

Mark

Use highlighted text to draw attention to a specific term or phrase within a paragraph.

1
Use <mark>highlighted text</mark> to draw attention to a specific term.

Horizontal rule

A thematic break rendered as a full-width border:

1
---