How to Generate Markdown Files from Astro Content Collections

What You’ll Learn

This guide shows you how to automatically generate clean markdown files from your Astro content collections. You’ll learn how to:

• Install and configure the astro-markdown-export plugin
• Customize the output to suit your needs
• Access the generated markdown files

Why Generate Markdown Files?

When Astro builds your site, your markdown content gets converted to HTML. This is great for browsers but creates two problems:

1. AI tools can’t easily process your content (ChatGPT, Claude, etc.)
2. Programmatic access to your content becomes difficult

By generating clean markdown files during build, you solve both problems without changing your workflow.

Quick Installation

# Install with npm
npm install astro-markdown-export

# Install with pnpm
pnpm add astro-markdown-export

# Install with yarn
yarn add astro-markdown-export

Basic Setup

Add to your Astro config file:

// astro.config.mjs or astro.config.ts
import { defineConfig } from "astro/config";
import markdownExport from "astro-markdown-export";

export default defineConfig({
  integrations: [
    markdownExport({
      siteUrl: "https://yourdomain.com",
    }),
  ],
});

Configuration Options

What Gets Generated

When you run astro build, the plugin:

1. Reads your markdown files from contentDir
2. Creates enhanced markdown files in dist/outputDir/
3. Adds source URLs and any additional frontmatter

Example Output

Original content file:

---
title: My Post
description: A sample post
---

# Content here

Generated markdown file:

---
title: My Post
description: A sample post
source_url:
  html: https://yourdomain.com/posts/my-post
  md: https://yourdomain.com/posts/my-post.md
---

# Content here

Practical Use Cases

1. AI Content Processing

Make your content available to AI tools like ChatGPT or Claude by pointing them to your generated markdown files. This works better than HTML because:

• Clean markdown is easier for AI to parse
• Frontmatter provides structured metadata
• Source URLs ensure proper attribution

2. Content API

Use the generated files as a simple content API:

// Example: Fetch a markdown post programmatically
async function fetchPost(slug) {
  const response = await fetch(`https://yourdomain.com/posts/${slug}.md`);
  return response.text();
}

3. Offline Documentation

Provide downloadable markdown versions of your documentation for users who prefer reading offline.

Advanced Configuration

Custom Frontmatter

markdownExport({
  siteUrl: "https://yourdomain.com",
  additionalFrontmatter: {
    generator: "My Site",
    version: "1.0.0",
    license: "CC-BY-4.0",
    ai_index: true,
  },
});

Custom Content Directory

If your content is in a non-standard location:

markdownExport({
  contentDir: "src/content/docs",
  outputDir: "documentation",
});

Troubleshooting

Files Not Generated

Check that:

1. Your content files have valid frontmatter
2. The contentDir path is correct
3. You’re running a full astro build (not dev mode)

Wrong URLs in Frontmatter

Ensure your siteUrl is set correctly in the plugin options or via the SITE_URL environment variable.

Source Code and Contributions

The plugin is open source and available on:

• npm
• GitHub

Contributions and feature requests are welcome!

Compatibility

• Requires Astro 5.0.0 or higher
• Works with all Astro content collections
• Compatible with all deployment targets