---
title: Astro Configuration Deep Dive — isHistory
description: Explore Astro's markdown configuration options with the classic engine.
url: "https://ishistory.org/blog/configuration-deep-dive"
type: static
generatedAt: "2026-06-01T11:07:55.641Z"
---

# Astro Configuration Deep Dive
    May 30, 2026    Astro Explorer    2 min read
Explore Astro's markdown configuration options with the classic engine.

astro, configuration, plugins

May 30, 2026
   [astro](/tags/#tag-astro)[configuration](/tags/#tag-configuration)[plugins](/tags/#tag-plugins)      On this page
## 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](/blog/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](/blog/markdown-tips/)

See [getting-started](/blog/getting-started/) for the basics or [markdown-tips](/blog/markdown-tips/) for writing tips.

### Share this post