DEV Community

Mohammed Shaheem P
Mohammed Shaheem P

Posted on

How to Generate Markdown Files from Astro Content Collections

#javascript #tutorial #tooling #ai

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
Enter fullscreen mode Exit fullscreen mode

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'
    })
  ]
});
Enter fullscreen mode Exit fullscreen mode

Configuration Options

Option Type Default Purpose
siteUrl string process.env.SITE_URL URL for source attribution
contentDir string 'src/content/blog' Where to find your content
outputDir string 'posts' Where to output markdown files
includeSourceUrls boolean true Add source URLs to frontmatter
additionalFrontmatter object {} Add custom frontmatter fields

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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();
}
Enter fullscreen mode Exit fullscreen mode

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
  }
})
Enter fullscreen mode Exit fullscreen mode

Custom Content Directory

If your content is in a non-standard location:

markdownExport({
  contentDir: 'src/content/docs',
  outputDir: 'documentation'
})
Enter fullscreen mode Exit fullscreen mode

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:

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

Buy Me A Coffee

Top comments (0)