Astro Configuration Deep Dive

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.

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:

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:

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

Callouts with rehype-callouts

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

[rehypeCallouts, { theme: 'obsidian' }]

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

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

TailwindCSS Setup

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

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:

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.