isHistory

Getting Started with Astro Markdown

Astro Explorer — Sun, 31 May 2026 00:00:00 GMT

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.

Note

This project uses content collections with a Zod schema for type-safe frontmatter validation. Every blog post must have a title and date, while author, description, tags, and draft are optional with sensible defaults.

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

astro.config.mjs

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'],
    }),
  ],
});

highlight-example.js

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

Tip

Astro’s island architecture means you only ship JavaScript for the interactive parts of your page. Everything else is pure, static HTML — fast by default.

Warning

Make sure to check peer dependency compatibility when using @astrojs/tailwind with Astro v6.

Tables

Feature	Classic Engine	Remark Integration
Built-in	Yes	No (install needed)
Syntax Highlight	Shiki	Shiki
Config	`markdown.*`	Integration config

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):

Category	Integration	Purpose
Markdown	remark-math	LaTeX math parsing
remark-extended-table	Rowspan/colspan tables
@flowershow/remark-wiki-link	Obsidian-style [[getting-started	wiki-links]]
Rendering	rehype-katex	Math display via KaTeX
rehype-callouts	Styled callout boxes
astro-expressive-code	Beautiful code blocks

Colspan example (cells spanning multiple columns):

Quarter	Revenue	Expenses	Profit
Q1 2026	$12,000	$8,000	$4,000
Q2 2026	$15,000	$9,500	$5,500
H1 Total	$9,500

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

Tip

Mermaid supports many diagram types: flowcharts, sequence diagrams, class diagrams, state diagrams, ER diagrams, Gantt charts, pie charts, and more. See the Mermaid documentation for the full syntax reference.

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!

Astro Configuration Deep Dive

Astro Explorer — Sat, 30 May 2026 00:00:00 GMT

Understanding `astro.config.mjs`

The astro.config.mjs file is the heart of your Astro project. It controls everything from build output to Markdown processing. When using the classic Markdown engine, all your Markdown settings live under the markdown key.

Info

This project combines multiple remark and rehype plugins in a single pipeline: wiki-links, math, extended tables, callouts, and expressive code — all configured in one place.

Markdown Configuration Options

Syntax Highlighting with Expressive Code

This project uses astro-expressive-code instead of the default Shiki for richer code block features. Expressive Code adds frame titles, text markers, diff highlighting, and word-wrap:

astro.config.mjs

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

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

Expressive Code handles its own CSS automatically — no manual imports needed. It creates a hashed CSS file and injects it into pages that contain code blocks.

Wiki Link Configuration

The @flowershow/remark-wiki-link plugin enables Obsidian-style [[wiki_links]] in your Markdown. It’s configured as a remark plugin:

astro.config.mjs

[
  wikiLinkPlugin,
  {
    format: 'shortestPossible',
    aliasDivider: '|',
    className: 'internal',
    newClassName: 'new',
    urlResolver: ({ filePath, heading }) => {
      const slug = filePath.replace(/\.md$/, '');
      return heading ? `/blog/${slug}#${heading}` : `/blog/${slug}`;
    },
  },
]

Tip

You can link between pages using [[getting-started]] or create aliases with [[getting-started|the intro]]. Try it: Go to Getting Started.

Callouts with rehype-callouts

The rehype-callouts plugin transforms blockquote-based callouts into styled boxes. It supports Obsidian, GitHub, and VitePress themes:

astro.config.mjs

[rehypeCallouts, { theme: 'obsidian' }]

The callout CSS is imported from the package directly in your global stylesheet:

@import 'rehype-callouts/theme/obsidian';

Warning

The @astrojs/tailwind integration is deprecated for Tailwind v4. If you upgrade to Tailwind v4, switch to @tailwindcss/vite instead.

TailwindCSS Setup

TailwindCSS is integrated via @astrojs/tailwind with @tailwindcss/typography for prose styling:

astro.config.mjs

tailwind({ applyBaseStyles: false })

Math Support

remark-math parses LaTeX math syntax and rehype-katex renders it. KaTeX CSS is imported from the installed dependency:

@import 'katex/dist/katex.min.css';

Extended Tables

remark-extended-table adds rowspan (^) and colspan (>) support. It requires passing extendedTableHandlers to the remarkRehype config:

astro.config.mjs

remarkRehype: {
  handlers: { ...extendedTableHandlers },
}

Best Practices

Keep your astro.config.mjs simple — only configure what you need
Use content collections with Zod schemas for type-safe frontmatter
Let plugins handle their own CSS — don’t override unless necessary
Organize Markdown files in src/content/blog/ for clean routing
Use wiki links to connect related content: markdown-tips

See getting-started for the basics or markdown-tips for writing tips.

Markdown Tips and Tricks

Astro Explorer — Fri, 29 May 2026 00:00:00 GMT

Level Up Your Markdown

Markdown is simple by design, but there are plenty of tricks that can make your content even better. Here are some tips that work great with Astro’s classic Markdown engine and the plugins in this project.

1. Use Callouts for Important Information

With rehype-callouts, you get Obsidian-style callouts. Use them to draw attention to important information:

Note

Callouts are perfect for highlighting important information that readers shouldn’t miss.

Tip

You can use callouts to suggest best practices or helpful shortcuts.

Warning

Use warning callouts to alert readers about common pitfalls or breaking changes.

Important

Critical information that must be followed goes in important callouts.

Example

Callouts support many types including note, tip, warning, important, example, question, success, failure, and more.

2. Wiki Links for Interconnected Content

Connect your pages using wiki links instead of traditional relative URLs:

Traditional: [Getting Started](/blog/getting-started/)
Wiki link: [[getting-started]] → getting-started

Tip

Wiki links are easier to maintain because they reference content by name, not file path. If you reorganize your pages, you only need to update the permalink mapping, not every link.

You can also use aliases for cleaner link text:

[[configuration-deep-dive|config guide]] → config guide

3. Expressive Code Features

The astro-expressive-code integration gives you super-powered code blocks:

Line numbers:

server.ts

import express from 'express';

const app = express();
const PORT = 3000;

app.get('/', (req, res) => {
  res.json({ message: 'Hello from Astro!' });
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

Marked and highlighted lines:

config.js

const siteName = "Astro Blog";
const version = "6.4.2";
const engine = "classic"; // This line is marked
const features = [
  "tailwind",  // These lines are inserted
  "expressive-code",
];

Diff-style highlighting:

changes.diff

const oldWay = "shiki";
const newWay = "expressive-code";

Astro.glob('./*.md');
import.meta.glob('./*.md', { eager: true });

4. Math with KaTeX

This project supports LaTeX math via remark-math and rehype-katex. You can write inline math or display equations:

Inline math: The Euler identity $e^{iπ} + 1 = 0$ is one of the most beautiful equations in mathematics.

Display math:

\int_{- \infty \infty} e^{- x^{2}} d x = π

The quadratic formula:

x = \frac{- b \pm b ^{2} - 4 a c}{2 a}

Maxwell’s equations in differential form:

\nabla \cdot E \nabla \cdot B \nabla \times E \nabla \times B = \frac{ρ}{ε _{0}} = 0 = - \frac{\partial B}{\partial t} = μ_{0} J + μ_{0} ε_{0} \frac{\partial E}{\partial t}

Tip

Use $...$ for inline math and $$...$$ for display (block) math. KaTeX supports a wide range of LaTeX commands — see the KaTeX supported functions reference.

5. Extended Tables

Use ^ for rowspan and > for colspan in tables:

Category	Plugin	Type
Markdown	remark-math	Math parsing
remark-extended-table	Extended tables
@flowershow/remark-wiki-link	Wiki links
Rendering	rehype-katex	Math display
rehype-callouts	Callout boxes
astro-expressive-code	Code blocks

6. Use HTML When Needed

Markdown doesn’t cover every HTML element. When you need something more — like a detail/summary collapse or a custom container — you can mix HTML directly into your Markdown:

<details>
  <summary>Click to expand</summary>
  This content is hidden by default!
</details>

7. Task Lists

You can create task lists (checkboxes) using brackets:

Set up Astro project
Configure classic Markdown engine
Add TailwindCSS via @astrojs/tailwind
Set up astro-expressive-code
Configure wiki-link plugin
Add remark-math + rehype-katex
Configure rehype-callouts
Add remark-extended-table
Add more features
Deploy to production

Keep Writing!

The best way to get comfortable with Markdown is to write with it regularly. Astro makes it easy — just create .md files in src/content/blog/ and let the framework handle the rest. Check out getting-started for the basics or configuration-deep-dive for advanced config.

isHistory

Getting Started with Astro Markdown

Why Astro with Markdown?

Frontmatter

Wiki Links

Code Blocks with Expressive Code

Markdown Features

Text Formatting

Callouts

Tables

Extended Tables (Rowspan & Colspan)

Mermaid Diagrams

What’s Next?

Astro Configuration Deep Dive

Understanding astro.config.mjs

Markdown Configuration Options

Syntax Highlighting with Expressive Code

Wiki Link Configuration

Callouts with rehype-callouts

TailwindCSS Setup

Math Support

Extended Tables

Best Practices

Markdown Tips and Tricks

Level Up Your Markdown

1. Use Callouts for Important Information

2. Wiki Links for Interconnected Content

3. Expressive Code Features

4. Math with KaTeX

5. Extended Tables

6. Use HTML When Needed

7. Task Lists

Keep Writing!

Understanding `astro.config.mjs`