Astro Markdown Export

An Astro integration that generates static markdown files from your content collections during build. Supports both .md and .mdx files. This is useful for:

• Making your content AI-friendly by providing raw markdown
• Enabling programmatic access to your content
• Creating downloadable versions of your documentation
• Improving content portability and integration with other tools
• Exporting MDX content as plain markdown for wider compatibility

Installation

# Using npm
npm install astro-markdown-export

# Using yarn
yarn add astro-markdown-export

# Using pnpm
pnpm add astro-markdown-export

Usage

Add the integration to your astro.config.mjs or astro.config.ts:

import { defineConfig } from 'astro/config';
import markdownExport from 'astro-markdown-export';

export default defineConfig({
  // ...other config
  integrations: [
    // ...other integrations
    markdownExport({
      // options (all optional)
      siteUrl: 'https://example.com',
      contentDir: 'src/content/blog',
      outputDir: 'posts',
      includeSourceUrls: true,
      normalizeExtension: true,
      additionalFrontmatter: {
        generator: 'Astro Markdown Export',
        version: '1.0.0'
      }
    }),
  ],
});

Configuration Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | siteUrl | string | process.env.SITE_URL or 'https://example.com' | The site URL to use in frontmatter | | contentDir | string | 'src/content/blog' | Content directory path relative to project root | | outputDir | string | 'posts' | Output directory path for markdown files relative to build output | | includeSourceUrls | boolean | true | Whether to include source URLs in frontmatter | | normalizeExtension | boolean | true | Whether to normalize all outputs to .md extension (including .mdx files) | | additionalFrontmatter | object | {} | Custom fields to add to frontmatter |

How It Works

During the build process, this integration:

1. Reads all markdown (.md) and MDX (.mdx) files from your content directory
2. Extracts and enhances the frontmatter
3. Generates static markdown files in your build output
4. Adds source URLs to the frontmatter (if enabled)
5. Normalizes file extensions to .md by default (configurable)

The generated markdown files will be available at /{outputDir}/{slug}.md in your built site.

Example Output

For a blog post with the following frontmatter:

---
title: How to Setup your MacBook Air M2 for Software Development
description: A detailed guide to setting up your M1/M2 MacBook for development
pubDatetime: 2022-11-07T00:00:00Z
tags:
  - macbook
  - setup
---

The generated markdown file will include enhanced frontmatter:

---
title: How to Setup your MacBook Air M2 for Software Development
description: A detailed guide to setting up your M1/M2 MacBook for development
pubDatetime: 2022-11-07T00:00:00Z
tags:
  - macbook
  - setup
source_url:
  html: https://example.com/posts/how-to-setup-your-macbook-air-m2-for-software-development
  md: https://example.com/posts/how-to-setup-your-macbook-air-m2-for-software-development.md
---

# Original content here

MDX Support

This integration fully supports MDX files (.mdx) alongside regular markdown files (.md).

Extension Normalization

By default, all files are exported with a .md extension for consistency and wider compatibility:

• blog-post.md → blog-post.md
• interactive-post.mdx → interactive-post.md

This means both .md and .mdx content will be accessible at {slug}.md paths.

Preserving Original Extensions

If you prefer to keep the original file extensions (e.g., to distinguish MDX from markdown), set normalizeExtension: false:

markdownExport({
  normalizeExtension: false
})

With this setting:

• blog-post.md → blog-post.md
• interactive-post.mdx → interactive-post.mdx

Note: When exporting MDX files, JSX components and imports are preserved in the output. The exported content remains valid MDX but may not render correctly if consumed as plain markdown.

Benefits for AI Tools

This format is ideal for AI tools because:

1. Structured Metadata: Clear separation of metadata from content
2. Source Attribution: Original URLs are included for reference
3. Contextual Information: Tags and description provide additional context
4. Proper Formatting: YAML frontmatter is widely recognized by AI tools

Use Cases

AI Crawlers

AI tools like ChatGPT can more effectively process your content when it's available in raw markdown format with proper frontmatter.

Documentation

Provide downloadable markdown versions of your documentation for offline use.

Content Syndication

Easily share your content with other platforms that accept markdown.

Data Portability

Ensure your content is available in a portable, future-proof format.

Compatibility

• Astro 5.0.0 and above
• Works with all Astro content collections
• Compatible with all Astro deployment targets

License

MIT