What is it

Markdown is a lightweight markup language created by John Gruber in 2004. It uses simple plain-text formatting syntax that can be converted to HTML and other formats. The goal was to make writing for the web as readable as possible—the source should look good even without rendering. From GitHub READMEs to Obsidian notes to this very blog, Markdown is everywhere.

MDX extends Markdown by allowing you to import and use React/JSX components directly in your content. It’s the bridge between static documentation and interactive experiences—you get the simplicity of Markdown with the power of components when you need them.

My Opinion

Markdown is one of those rare technologies that got it right the first time. It’s been around for two decades and still doesn’t need replacing. The syntax is intuitive enough that non-technical people can learn it in minutes, yet powerful enough to write entire books. It’s the lingua franca of developer documentation, and for good reason.

The Plain-Text Philosophy

Markdown files are just text. No proprietary formats, no vendor lock-in, no binary blobs. You can read them in any text editor, version control them with Git, and they’ll still be readable in 50 years. This is the same local-first philosophy that makes Obsidian so appealing—your content is yours, forever portable.

The syntax doubles as formatting. Headers are visually distinct with # symbols. Lists look like lists. Code blocks are obvious. You can read a Markdown file and understand its structure without rendering it. This wasn’t an accident—it was the entire design goal.

MDX: When Markdown Isn’t Enough

Pure Markdown covers 90% of documentation needs, but sometimes you need interactivity. MDX lets you drop React components into your Markdown without leaving the writing flow. A callout component here, an interactive demo there, a chart that pulls live data—all seamlessly integrated with your prose.

Astro embraces MDX as a first-class citizen, which is why this blog uses it. The callouts, image galleries, and other custom elements you see on these pages are MDX components living alongside standard Markdown. The authoring experience stays simple while the output can be as rich as needed.

The Fragmentation Problem

Here’s the ugly truth: there’s no single “Markdown.” CommonMark tried to standardize the basics, GitHub Flavored Markdown added tables and task lists, and every tool has its own extensions. Obsidian uses [[wikilinks]], Hugo has shortcodes, Notion does its own thing entirely.

This fragmentation means your Markdown files aren’t always portable between tools. The solution is to stick close to CommonMark for the core content and use tool-specific features sparingly. Or embrace MDX and accept that your components are the extensions.

The Learning Curve That Isn’t

Markdown’s greatest strength is how quickly anyone can learn it. Bold is **bold**. Italics is *italics*. Links are [text](url). Headers are #. Lists are -. That’s genuinely 80% of what most people need. The remaining syntax—tables, code blocks, footnotes—is learned as needed.

Compare this to HTML, LaTeX, or even rich text editors with their hidden formatting. Markdown is transparent. What you see is what you mean.

Example: Formatting Reference

Below is a comprehensive reference of all the Markdown, extended Markdown, and MDX features available in this blog theme. Use this as both a reference guide and a showcase of what’s possible.

Basic Formatting

Text Emphasis

• Bold text using **bold** or __bold__
• Italic text using *italic* or _italic_
• Bold and italic using ***text***
• Strikethrough using ~~text~~
• Highlighted text using ==text==
• Inline code using backticks

Headings

Heading 1

Heading 2

Heading 3

Heading 4

Heading 5

Heading 6

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Callouts and Admonitions

Our theme supports Obsidian-style callouts with proper icons and styling. Each callout type has its own color scheme and matching Lucide icon.

Basic Callouts

Custom Titles

Collapsible Callouts

You can make callouts collapsible by adding + (expanded by default) or - (collapsed by default) after the callout type:

Extended Callout Types

Callouts with Formatting

Media Content

Images

Single Image With Caption

Photo by Antoine Rault on Unsplash

Multiple Image Layouts

This theme automatically arranges consecutive images in responsive grid layouts based on the number of images. Images can be placed together without empty lines between them to create these layouts.

Two Images Side by Side

Three Images in a Row

Four Images in a Row

How to Use Multiple Images / Gallery

Simply place multiple images together without empty lines between them:

![Image 1](image1.jpg)
![Image 2](image2.jpg)
![Image 3](image3.jpg)

On mobile devices, all layouts switch to a single column for better readability.

Linked Images

[![Mountains](attachments/mountains.png)](https://obsidian.md)

Lists

Unordered Lists

• First item
• Second item
  • Nested item
  • Another nested item
    • Deeply nested item
• Third item

Ordered Lists

1. First step
2. Second step
   1. Sub-step A
   2. Sub-step B
      1. Sub-sub-step
3. Third step

Task Lists

• Completed task
• Incomplete task
• Another completed task
  • Nested incomplete task
  • Nested completed task
• Final incomplete task

Links and References

External Links

Here’s an external link.

Reference Links

This is a reference link and this is another reference link.

Code Blocks

Inline Code

Use const variable = 'value' for inline code snippets.

JavaScript

function greetUser(name) {
  console.log(`Hello, ${name}!`);
  return `Welcome to our blog, ${name}`;
}

const user = "Developer";
greetUser(user);

Python

def calculate_fibonacci(n):
    """Calculate the nth Fibonacci number."""
    if n <= 1:
        return n
    return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)

# Example usage
for i in range(10):
    print(f"F({i}) = {calculate_fibonacci(i)}")

CSS

.button {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border: none;
  border-radius: 8px;
  color: white;
  padding: 12px 24px;
  transition: transform 0.2s ease;
}

.button:hover {
  transform: translateY(-2px);
}

Bash/Shell

#!/bin/bash
echo "Setting up development environment..."

# Install dependencies
npm install

# Start development server
npm run dev

echo "Development server started on http://localhost:3000"

Tables

Basic Tables

Feature	Supported	Notes
Markdown	Yes	Full CommonMark support
Wikilinks	Yes	Obsidian-style double brackets
Callouts	Yes	Multiple types with icons
Math	Yes	LaTeX math with KaTeX rendering
Diagrams	Yes	Mermaid diagram support

Advanced Tables

Language	Use Case	Performance	Learning Curve
JavaScript	Web Development	High	Easy
Python	Data Science	Medium	Easy
Rust	Systems Programming	Very High	Hard
Go	Backend Services	High	Medium

Blockquotes

Simple Quotes

The best way to predict the future is to invent it.
— Alan Kay

Nested Quotes

This is a top-level quote.

This is a nested quote within the first quote.

And this is a quote nested even deeper.

Back to the top level.

Horizontal Rules

You can create horizontal rules using three dashes:

---

Or three asterisks:

---

Or three underscores:

---

HTML Elements

You can use HTML directly. Here are some examples:

Click to expand

This content is hidden by default and can be expanded by clicking the summary.

Small text for fine print ^Superscript _Subscript

Keyboard Shortcuts

Press Ctrl + C to copy and Ctrl + V to paste.

Use Cmd + K to open the command palette.

Special Characters and Symbols

• Copyright: ©
• Trademark: ™
• Registered: ®
• Arrows: ← ↑ → ↓ ↔ ↕
• Symbols: ★ ☆ ♠ ♣ ♥ ♦
• Currency: $ € £ ¥

Buttons

These buttons use your existing color palette and adapt perfectly to light/dark themes. Wrap them in internal or external links if you prefer:

<div class="btn-group-center my-8">
  <a href="https://google.com" class="no-styling no-underline" target="_blank"><button class="btn btn-primary">Primary Action</button></a>
  <a href="https://google.com" class="no-styling no-underline" target="_blank"><button class="btn btn-secondary">Secondary</button></a>
    <a href="https://google.com" class="no-styling no-underline" target="_blank"><button class="btn btn-outline">Outlined</button></a>
      <a href="https://google.com" class="no-styling no-underline" target="_blank"><button class="btn btn-ghost">Subtle</button></a>
</div>

Works with Obsidian

All of these formatting options should also appear in Obsidian, with some differences depending on the theme you use.

Quick Reference

• Bold: **text** or __text__
• Italic: *text* or _text_
• Code: `code`
• Highlight: ==text==
• Links: [text](url) or [[wikilink]]
• Images: ![alt](url)
• Lists: - or 1. for ordered
• Tasks: - [ ] and - [x]
• Tables: Use | to separate columns
• Quotes: Start lines with >
• Callouts: > [!TYPE]
• Horizontal rule: ---

Conclusion

Markdown is the rare standard that earned its ubiquity. It’s simple enough for anyone to learn, powerful enough for serious documentation, and portable enough to outlive any single tool. Combined with MDX for when you need interactivity, it’s the ideal foundation for content that needs to be both writable and readable by humans. If you’re not already writing in Markdown, you should be.