astro-markdown-prerender

An Astro integration that automatically sets route.prerender based on frontmatter properties in your Markdown files.

Installation

npm install astro-markdown-prerender

Usage

Add the integration to your astro.config.ts:

import { defineConfig } from 'astro/config';
import markdownPrerender from 'astro-markdown-prerender';

export default defineConfig({
  integrations: [
    markdownPrerender()
  ],
});

Then in your Markdown files, add the prerender property to your frontmatter:

---
title: "My Blog Post"
prerender: true
---

# My Blog Post

This page will be prerendered at build time.

---
title: "Dynamic Page"
prerender: false
---

# Dynamic Page

This page will be rendered on-demand.

Configuration

The integration accepts the following options:

export interface MarkdownPrerenderOptions {
  /**
   * Whether to log debug information about processed files
   * @default false
   */
  verbose?: boolean;

  /**
   * Custom property name to look for in frontmatter
   * @default 'prerender'
   */
  frontmatterProperty?: string;

  /**
   * Default prerender value when property is not found
   * @default undefined (no change to route.prerender)
   */
  defaultValue?: boolean;

  /**
   * Whether to prerender all markdown files regardless of frontmatter
   * @default false
   */
  prerenderAll?: boolean;
}

Examples

Enable verbose logging

import markdownPrerender from 'astro-markdown-prerender';

export default defineConfig({
  integrations: [
    markdownPrerender({
      verbose: true
    })
  ],
});

Use a custom frontmatter property

import markdownPrerender from 'astro-markdown-prerender';

export default defineConfig({
  integrations: [
    markdownPrerender({
      frontmatterProperty: 'static'
    })
  ],
});

Then in your Markdown:

---
title: "My Page"
static: true
---

# My Page

Set a default value

import markdownPrerender from 'astro-markdown-prerender';

export default defineConfig({
  integrations: [
    markdownPrerender({
      defaultValue: true // All markdown files will be prerendered by default
    })
  ],
});

Force prerender all markdown files

import markdownPrerender from 'astro-markdown-prerender';

export default defineConfig({
  integrations: [
    markdownPrerender({
      prerenderAll: true // All .md files will be prerendered, ignoring frontmatter
    })
  ],
});

When prerenderAll is enabled, all markdown files will be prerendered regardless of their frontmatter values. This is useful when you want to ensure all markdown content is static without having to modify individual files.

How it works

This integration uses the astro:route:setup hook to:

1. Check if the route component is a Markdown file (.md extension)
2. If prerenderAll is enabled, immediately set route.prerender = true and skip frontmatter parsing
3. Otherwise, parse the frontmatter using gray-matter
4. Look for the specified property (default: prerender)
5. Set route.prerender to the value found in frontmatter, or use defaultValue if specified

Use Cases

• Mixed rendering strategies: Some blog posts static, others dynamic
• Content management: Let content creators control rendering per page
• Performance optimization: Prerender important pages, keep others dynamic
• A/B testing: Dynamically render test pages while keeping others static
• Force static site: Use prerenderAll: true to ensure all markdown content is prerendered
• Migration scenarios: Quickly convert all markdown to static without editing individual files

Requirements

• Astro 4.0+ or 5.0+
• Node.js 18+

License

MIT

Contributing

Issues and pull requests are welcome on GitHub.