Skip to main content
Back to Blog

The Complete Markdown Showcase: Every Element, Every Variant

A comprehensive reference post exercising every Markdown element supported by isHistory — CommonMark, GFM, Obsidian Flavored Markdown, KaTeX math, callouts, code blocks, tables, blockquotes, and every extended HTML element. Use this as a living style guide.

I
Ishaan
| | 17 min read | 3,366 words
markdown reference style-guide
Share X Reddit LinkedIn

Overview

This post is a living style guide for the isHistory markdown pipeline. Every element that the pipeline can render is exercised below, with multiple variants where applicable. If you’re authoring a new post and want to see how a particular syntax will look, find it here.

The pipeline supports:

  • CommonMark — the baseline spec (headings, paragraphs, lists, code, links, images, blockquotes, horizontal rules)
  • GFM (GitHub Flavored Markdown) — tables, task lists, strikethrough, autolinks, deletion/insertion
  • Obsidian Flavored Markdown — callouts (> [!note], > [!tip], > [!important], > [!warning], > [!caution]), wiki-links ([[target]], [[target|alias]])
  • KaTeX math — inline ($...$) and display ($$...$$) math
  • rehype-pretty-code — Shiki-powered syntax highlighting with dual themes (light/dark), line highlighting, line numbers, diff syntax, code block titles
  • Extended HTML elements — <kbd>, <mark>, <abbr>, <details>, <summary>, <dl>, <sub>, <sup>, <del>, <ins>, <cite>, <q>, <address>

Headings (h2 through h6)

The page title is the only <h1>. Inside the article body, headings start at h2. The TOC in the sidebar auto-generates from h2 and h3.

This is an h3

This is an h4

This is an h5
This is an h6

Heading anchor links (the chain icon) appear on hover to the left of every h2–h6. Clicking one updates the URL hash for deep-linking.

Paragraphs and Inline Formatting

A standard paragraph. Markdown wraps consecutive lines into a single paragraph. To start a new paragraph, leave a blank line between blocks.

A second paragraph immediately after. The vertical rhythm comes from the Tailwind Typography plugin’s default prose-lg spacing.

Bold text uses double asterisks. Alternatively, double underscores. Italic text uses single asterisks. Alternatively, single underscores. Bold italic uses triple asterisks. Strikethrough uses double tildes (GFM). Inline code uses single backticks.

You can also use the legacy HTML tags: bold, italic, strikethrough, underline, teletype, small text, big text.

Inline link: isHistory homepage. Link with title attribute (hover): Astro docs. Reference-style link: Astro. Auto-link (bare URL): https://astro.build.

Internal links use relative paths: blog index, series index. Wiki-links (Obsidian-style) also work: astro-website-cms-obsidian-plugin resolves to the file’s permalink. Wiki-links with aliases: the CMS post.

External links automatically get target="_blank" and rel="noopener noreferrer" via rehype-external-links. Example: GitHub.

Emphasis and Semantic Inline Elements

HTML abbreviations get a dotted underline and a tooltip on hover. Ctrl + K opens search. Esc closes modals.

Use mark to highlight text. Use cite for citation titles. Use inline quotes for short quotations (auto-wrapped in curly quotes). Use sample output for computer output.

Subscript: H2O. Superscript: E = mc2. Combination: an2 + bn2 = cn2.

Deleted text shows removals. Inserted text shows additions. These are useful for editorial revisions.

Lists

Unordered List

  • First item
  • Second item
    • Nested item (level 2)
      • Nested item (level 3)
    • Back to level 2
  • Third item

Ordered List

  1. First item
  2. Second item
  3. Third item
    1. Nested ordered (level 2)
    2. Another nested
  4. Fourth item

Mixed List

  1. Ordered item one
    • Unordered nested under it
    • Another unordered
  2. Ordered item two
    • More nesting
      1. Deeply nested ordered

Task List (GFM)

  • Completed task
  • Incomplete task
  • Another completed task with bold and italic text inside
  • A task with a link inside

Task list items get custom checkboxes — checked items have a strikethrough on their text.

Definition List

Astro
A modern static site generator that ships zero JavaScript by default.
Tailwind CSS
A utility-first CSS framework for rapid UI development.
KaTeX
A fast, easy-to-use JavaScript library for TeX math rendering on the web.

Blockquotes — Every Variant

Simple Blockquote

This is a simple blockquote. It has one paragraph and no nesting.

Multi-Paragraph Blockquote

First paragraph of the blockquote.

Second paragraph, separated by a blank line inside the blockquote.

Nested Blockquote

Outer blockquote, level 1.

Inner blockquote, level 2.

Still inside the inner blockquote.

Blockquote with Attribution

The best way to predict the future is to invent it.

— Alan Kay

Blockquote with Rich Content

Bold, italic, strikethrough, inline code, and a link — all work inside blockquotes.

Even a nested list:

  • Item one

  • Item two

And a code block:

JavaScript
const x = 42;

Pull Quote (auto-styled)

Design is not just what it looks like and feels like. Design is how it works.

— Steve Jobs

All blockquotes get the editorial pull-quote treatment: large italic text, decorative opening quotation mark, gradient background, indigo left border, and subtle shadow.

Tables — Every Variant

Simple Table

NameTypeDescription
AstroFrameworkStatic site generator
TailwindCSSUtility-first framework
KaTeXLibraryMath rendering

Table with Alignment

Left alignedCenter alignedRight aligned
leftcenterright
longer textlonger textlonger text
shortshortshort

Table with Inline Formatting

FeatureSyntaxResult
Bold**text**text
Italic*text*text
Strikethrough~~text~~text
Inline code`code`code
Link[text](url)text

Table with Many Rows (Zebra Striping)

Tables with 4+ rows get automatic zebra striping on alternating rows. Hover highlights the row with a subtle indigo tint.

#EraYearNotable Event
1Pre-history1843Ada Lovelace’s first algorithm
2Pre-history1936Turing machine paper
3Birth of AI1956Dartmouth Conference
4First winter1974Lighthill Report
5Expert systems1980Rise of MYCIN, XCON
6Second winter1987LISP machine market collapse
7Deep learning2012AlexNet wins ImageNet
8Transformer2017”Attention Is All You Need”
9Generative AI2022ChatGPT launches

Wide Table (Horizontal Scroll)

Wide tables overflow horizontally on small screens. On desktop, they fit within the prose column.

Column AColumn BColumn CColumn DColumn EColumn FColumn GColumn HColumn IColumn J
12345678910
alphabetagammadeltaepsilonzetaetathetaiotakappa

Callouts — Every Type

The rehype-callouts plugin (GitHub theme) supports five callout types. Each renders as a colored block with an SVG indicator and a title.

Callouts with Custom Titles

Callouts with Rich Content

Collapsible Callouts

Collapsed by default (click to expand)

The- after [!note] makes the callout collapsed by default. Users click the title to expand it. Useful for long asides that aren’t essential to the main flow.

Expanded by default (click to collapse)

The+ after [!note] makes the callout expanded by default but collapsible. Useful for content that should be visible initially but can be hidden.

Code Blocks — Every Variant

Plain Code Block (no language)

This is a plain code block with no language specified.No syntax highlighting is applied.

JavaScript

// A JavaScript code block with syntax highlightingconst greet = (name) => {  console.log(`Hello, ${name}!`);  return `Greetings, ${name}`;};greet('world');

TypeScript

// TypeScript with type annotationsinterface User {  id: number;  name: string;  email?: string;}function getUser(id: number): Promise<User> {  return fetch(`/api/users/${id}`).then((res) => res.json());}

Python

# Python with type hintsfrom typing import List, Optionaldef fibonacci(n: int) -> List[int]:    """Generate the first n Fibonacci numbers."""    if n <= 0:        return []    if n == 1:        return [0]    fibs = [0, 1]    for _ in range(2, n):        fibs.append(fibs[-1] + fibs[-2])    return fibsprint(fibonacci(10))

Bash / Shell

#!/usr/bin/env bash# A bash script exampleset -euo pipefailPROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"cd "$PROJECT_DIR"echo "Building project..."npm run buildecho "Deploying..."npx wrangler pages deploy dist

JSON

{  "name": "isHistory",  "version": "1.0.0",  "type": "module",  "scripts": {    "dev": "astro dev",    "build": "astro build",    "preview": "astro preview"  },  "dependencies": {    "astro": "^6.0.0",    "tailwindcss": "^4.0.0"  }}

CSS

/* CSS with nested selectors */.button {  display: inline-flex;  align-items: center;  padding: 0.5rem 1rem;  border-radius: 0.375rem;  background: #4f46e5;  color: #ffffff;  transition: background-color 0.2s ease;}.button:hover {  background: #4338ca;}

HTML

<!doctype html><html lang="en">  <head>    <meta charset="UTF-8" />    <title>Example</title>  </head>  <body>    <main>      <h1>Hello, world!</h1>      <p>This is an HTML code block.</p>    </main>  </body></html>

YAML

# YAML frontmatter exampletitle: "Sample Post"description: "A sample post for demonstration."pubDate: 2026-06-18tags:  - Markdown  - Referencedraft: false

SQL

-- SQL query exampleSELECT  u.id,  u.name,  COUNT(p.id) AS post_count,  MAX(p.created_at) AS last_postFROM users uLEFT JOIN posts p ON p.author_id = u.idWHERE u.created_at >= '2026-01-01'GROUP BY u.id, u.nameHAVING COUNT(p.id) > 0ORDER BY post_count DESCLIMIT 10;

Code Block with Title (filename)

import { defineConfig } from 'astro/config';export default defineConfig({  site: 'https://ishistory.pp.ua',  integrations: [],});

Code Block with Line Highlighting

Use {1,3-5} syntax to highlight specific lines:

const config = {  site: 'https://ishistory.pp.ua',  integrations: [],  markdown: {    shikiConfig: { theme: 'github-dark' },    syntaxHighlight: 'shiki',  },};

Code Block with Line Numbers

Use showLineNumbers to add line numbers:

function quicksort(arr) {  if (arr.length <= 1) return arr;  const pivot = arr[0];  const left = arr.slice(1).filter((x) => x < pivot);  const right = arr.slice(1).filter((x) => x >= pivot);  return [...quicksort(left), pivot, ...quicksort(right)];}

Diff Code Block

Use diff language to show additions/removals:

function greet(name) {-  console.log("Hello, " + name);+  console.log(`Hello, ${name}!`);+  return `Greetings, ${name}`;}greet("world");

Multiple Features Combined

Title + line numbers + line highlighting:

export function factorial(n: number): number {  if (n < 0) throw new Error('Negative input');  let result = 1;  for (let i = 2; i <= n; i++) {    result *= i;  }  return result;}export function binomial(n: number, k: number): number {  return factorial(n) / (factorial(k) * factorial(n - k));}

Inline Code

Inline code uses single backticks: const x = 42. Code inside a sentence: Array.prototype.map(). With special characters: <div className="foo" />. With backticks inside: `single backtick`.

Math — KaTeX

The pipeline supports inline math with $...$ and display math with $$...$$. Math is rendered by KaTeX.

Inline Math

The Pythagorean theorem: a2+b2=c2a^2 + b^2 = c^2. The area of a circle: A=πr2A = \pi r^2. Euler’s identity: eiπ+1=0e^{i\pi} + 1 = 0. A quadratic equation: x=−b±b2−4ac2ax = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}.

Inline math inherits the surrounding text color and respects line-height.

Display Math

∫−∞∞e−x2 dx=π\int_{-\infty}^{\infty} e^{-x^2} \, dx = \sqrt{\pi} ∑n=1∞1n2=π26\sum_{n=1}^{\infty} \frac{1}{n^2} = \frac{\pi^2}{6} ∂f∂x=lim⁡h→0f(x+h)−f(x)h\frac{\partial f}{\partial x} = \lim_{h \to 0} \frac{f(x+h) - f(x)}{h}

Matrices

[abcd][xy]=[ax+bycx+dy]\begin{bmatrix} a & b \\ c & d \end{bmatrix} \begin{bmatrix} x \\ y \end{bmatrix} = \begin{bmatrix} ax + by \\ cx + dy \end{bmatrix}

Aligned Equations

∇×B⃗=μ0J⃗+μ0ε0∂E⃗∂t∇×E⃗=−∂B⃗∂t∇⋅B⃗=0∇⋅E⃗=ρε0\begin{aligned} \nabla \times \vec{B} &= \mu_0 \vec{J} + \mu_0 \varepsilon_0 \frac{\partial \vec{E}}{\partial t} \\ \nabla \times \vec{E} &= -\frac{\partial \vec{B}}{\partial t} \\ \nabla \cdot \vec{B} &= 0 \\ \nabla \cdot \vec{E} &= \frac{\rho}{\varepsilon_0} \end{aligned}

Cases (Piecewise Functions)

f(x)={x2if x≥0−x2if x<0f(x) = \begin{cases} x^2 & \text{if } x \geq 0 \\ -x^2 & \text{if } x < 0 \end{cases}

Summation and Products

∏i=1ni=n!∑k=0n(nk)=2n\prod_{i=1}^{n} i = n! \qquad \sum_{k=0}^{n} \binom{n}{k} = 2^n

Limits and Calculus

lim⁡n→∞(1+1n)n=e≈2.71828…\lim_{n \to \infty} \left(1 + \frac{1}{n}\right)^n = e \approx 2.71828\ldots

Greek Letters and Symbols

α,β,γ,δ,ϵ,ζ,η,θ,ι,κ,λ,μ,ν,ξ,π,ρ,σ,τ,υ,ϕ,χ,ψ,ω\alpha, \beta, \gamma, \delta, \epsilon, \zeta, \eta, \theta, \iota, \kappa, \lambda, \mu, \nu, \xi, \pi, \rho, \sigma, \tau, \upsilon, \phi, \chi, \psi, \omega Γ,Δ,Θ,Λ,Ξ,Π,Σ,Υ,Φ,Ψ,Ω\Gamma, \Delta, \Theta, \Lambda, \Xi, \Pi, \Sigma, \Upsilon, \Phi, \Psi, \Omega

Math with Text

P(Event)=favorable outcomestotal outcomes×100%P(\text{Event}) = \frac{\text{favorable outcomes}}{\text{total outcomes}} \times 100\%

Horizontal Rules

A horizontal rule creates an editorial section break — a gradient line with a centered indigo dot. Three variants of syntax all produce the same result:

Above is a horizontal rule using three hyphens.

Above is a horizontal rule using three asterisks.

Above is a horizontal rule using three underscores.

Images

Astro logo (placeholder):

Astro logo placeholder

Images get a rounded border and subtle box-shadow. Long alt text appears in the figcaption styling if wrapped in a figure (using HTML).

A placeholder figure with a caption
Figures with figcaptions get centered, smaller, muted text below the image. Use this for editorial figures that need attribution or explanation.

Details and Summary (Disclosure Widget)

Click to expand — basic details element The `
` element creates a collapsible disclosure widget. The `` is the clickable header. Content below the summary is hidden until expanded.

Markdown works inside:

  • Lists
  • Bold and italic
  • Inline code
Multiple paragraphs inside details

First paragraph. Note the blank line above — it ensures proper paragraph spacing.

Second paragraph. Without the blank line, paragraphs would be squished together.

Even code blocks work:

console.log('inside a details element');
Expanded by default Add the `open` attribute to `
` to start expanded. Users can collapse it by clicking the summary.

Addresses and Citations

Written by Ishaan
isHistory Project
Email: ishistory@proton.me
Web: ishistory.pp.ua

As Alan Turing once wrote, “We can only see a short distance ahead, but we can see plenty there that needs to be done.”

Footnotes

GFM supports footnotes via the [^1] syntax1. Footnotes appear at the bottom of the document with a clickable reference link2.

Footnotes can also be inline3 like this.

Combination Examples

A Callout with Math Inside

A Table with Code and Math

OperationCodeMath
Square rootMath.sqrt(x)x\sqrt{x}
PowerMath.pow(x, n)xnx^n
Sumarr.reduce((a,b) => a+b, 0)∑i=1nxi\sum_{i=1}^{n} x_i
Integraln/a (numerical only)∫abf(x) dx\int_a^b f(x) \, dx

A Blockquote with a Code Block

“Code is like humor. When you have to explain it, it’s bad.” — Cory House

JavaScript
// Even bad code can be improvedfunction bad() {  return [1, 2, 3].map((x) => x * 2).filter((x) => x > 2).reduce((a, b) => a + b, 0);}

Edge Cases

Empty Elements

A horizontal rule with no content around it:

A paragraph immediately after a horizontal rule.

Special Characters

The pipe character | in tables needs escaping: | escaped pipe | in a table cell.

Less-than < and greater-than > should be escaped in code: <div> becomes &lt;div&gt; in raw HTML, but inside backticks <div> is fine.

Ampersands: AT&T, Tom & Jerry, P&G. In code: if (a && b). In URLs: ?a=1&b=2.

Emojis

Standard emojis work in markdown: 🚀 rocket, ✅ check, ❌ cross, ⚠️ warning, 💡 idea, 📌 pin, 🎯 target, 📝 memo. They render with the system emoji font.

Very Long Line

This is a single paragraph that contains a very long line of text without any line breaks in the source markdown. Markdown will wrap this to fit the available width automatically based on the prose container’s max-width. The 65ch optimal line length means the text wraps at approximately 65 characters per line, which is the recommended maximum for reading comfort per Baymard Institute research. Longer lines cause readers to lose their place when jumping from the end of one line to the start of the next; shorter lines force the eye to return too often, breaking rhythm. The 65ch value strikes the right balance for most body text.

Unicode and Internationalization

Latin: café, naïve, résumé, façade. Greek: α β γ δ ε ζ η θ ι κ λ μ. Cyrillic: А Б В Г Д Е Ж. Chinese: 你好世界. Japanese: こんにちは世界. Korean: 안녕하세요 세계. Arabic: مرحبا بالعالم. Hebrew: שלום עולם. Hindi: नमस्ते दुनिया. Thai: สวัสดีชาวโลก.

Right-to-left text: مرحبا بالعالم — wraps in a span with dir="rtl".

Summary

This post exercised:

  • 6 heading levels (h1 implicit, h2–h6 in body)
  • Paragraphs with inline formatting (bold, italic, strikethrough, code, mark, kbd, abbr, sub, sup, del, ins, cite, q, samp, small, big, tt, u)
  • Links (inline, reference, auto, internal, external, wiki-link)
  • Lists (unordered, ordered, nested, mixed, task list, definition list)
  • Blockquotes (simple, multi-paragraph, nested, with attribution, with rich content)
  • 5 callout types (note, tip, important, warning, caution) × 4 variants each (default, custom title, rich content, collapsible)
  • Tables (simple, aligned, with formatting, many-row, wide overflow)
  • Code blocks (10+ languages, with title, line highlighting, line numbers, diff, combined)
  • Math (inline, display, matrices, aligned, cases, summation, limits, Greek letters, with text)
  • Horizontal rules (3 syntaxes)
  • Images (inline, figure with caption)
  • Details/summary (collapsed, expanded, with rich content)
  • Addresses, citations, footnotes
  • Edge cases (special characters, emojis, long lines, Unicode, RTL text)

If you spot anything missing or rendering incorrectly, open an issue on the GitHub repo.

Footnotes

  1. This is the first footnote. Click the back arrow to return to the text. ↩

  2. Here’s one with multiple paragraphs and code.

    Indent paragraphs to include them in the footnote.

    code blocks work too

    And back to text. ↩

  3. This footnote is defined inline at the point of reference. ↩

Share this article X Reddit LinkedIn