---
title: Getting Started with Astro Markdown — isHistory
description: Learn how to create Markdown-powered pages in Astro using the classic engine.
url: "https://ishistory.org/blog/getting-started"
type: static
generatedAt: "2026-06-01T11:07:55.662Z"
---

# Getting Started with Astro Markdown
    May 31, 2026    Astro Explorer    3 min read
Learn how to create Markdown-powered pages in Astro using the classic engine.

astro, markdown, getting-started

May 31, 2026
   [astro](/tags/#tag-astro)[markdown](/tags/#tag-markdown)[getting-started](/tags/#tag-getting-started)      On this page
## 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-31author: "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](/blog/getting-started/)
 - `[[configuration-deep-dive]]` → [configuration-deep-dive](/blog/configuration-deep-dive/)
 - `[[markdown-tips]]` → [markdown-tips](/blog/markdown-tips/)

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

## 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](https://mermaid.js.org/) 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](/blog/configuration-deep-dive/) for detailed config options or [markdown-tips](/blog/markdown-tips/) for writing tips. Happy writing!

### Share this post