Getting Started with Astro Markdown

Why Astro with Markdown?

Astro provides first-class support for Markdown content. When you use Astro’s content collections, your Markdown files live in src/content/blog/ and are rendered through a dynamic [...slug].astro page. This gives you full control over layouts, metadata, and routing while keeping your content organized and type-safe with Zod schemas.

The classic Markdown engine in Astro processes your Markdown using the built-in pipeline — everything works out of the box with sensible defaults, and you extend it with remark and rehype plugins as needed.

Frontmatter

Every Markdown file includes a frontmatter block at the top. With content collections, the schema is validated at build time:

---
title: "My Blog Post"
date: 2026-05-31
author: "Jane Doe"
description: "A post about something interesting"
tags: [astro, markdown]
draft: false
---

The schema enforces that title is a string and date is a valid date. Optional fields like tags default to an empty array, and draft defaults to false.

Wiki Links

This project supports Obsidian-style wiki links via @flowershow/remark-wiki-link. You can link to other pages using double brackets:

• [[getting-started]] → getting-started
• [[configuration-deep-dive]] → configuration-deep-dive
• [[markdown-tips]] → markdown-tips

You can also use aliases for cleaner link text: [[configuration-deep-dive|the config guide]] → the config guide

Code Blocks with Expressive Code

import { defineConfig } from 'astro/config';
import tailwind from '@astrojs/tailwind';
import astroExpressiveCode from 'astro-expressive-code';

export default defineConfig({
  integrations: [
    tailwind(),
    astroExpressiveCode({
      themes: ['dracula', 'github-light'],
    }),
  ],
});

const greeting = "Hello, Astro!";
const version = "6.4.2";
const engine = "classic";
console.log(`${greeting} v${version} (${engine})`);

Markdown Features

Text Formatting

• Bold text using double asterisks
• Italic text using single asterisks
• Inline code using backticks
• Strikethrough using double tildes

Callouts

Tables

Extended Tables (Rowspan & Colspan)

With remark-extended-table, you can create tables with cells that span multiple rows or columns. The syntax uses > for colspan and ^ for rowspan:

Rowspan example (cells spanning multiple rows):

Colspan example (cells spanning multiple columns):

Mermaid Diagrams

With astro-mermaid, you can render diagrams and flowcharts directly in Markdown using the mermaid code fence:

graph TD
    A[Markdown Source] --> B{Astro Classic Engine}
    B --> C[Remark Plugins]
    B --> D[Rehype Plugins]
    C --> C1[wiki-link]
    C --> C2[remark-math]
    C --> C3[extended-table]
    D --> D1[autolink-headings]
    D --> D2[rehype-callouts]
    D --> D3[rehype-katex]
    C3 & C1 & C2 --> E[remark-rehype]
    D1 & D2 & D3 --> F[HTML Output]
    E --> F

You can also create sequence diagrams:

sequenceDiagram
    participant User
    participant Astro
    participant Plugin
    User->>Astro: Write Markdown with mermaid fence
    Astro->>Plugin: remark-mermaid intercepts code block
    Plugin->>Plugin: Replace with pre.mermaid placeholder
    Astro->>User: Serve HTML with client-side mermaid.js
    User->>Plugin: Browser renders SVG diagram

What’s Next?

Start creating your own Markdown files in src/content/blog/ and watch Astro transform them into fast, lightweight HTML pages. Check out configuration-deep-dive for detailed config options or markdown-tips for writing tips. Happy writing!