# Markdown Page Generation

Generates .md companion files and llms.txt from built HTML pages at build time.

> For the index of this section of the site, see [llms.txt](https://better-static-sites.github.io/llms.txt)

# Markdown Page Generation

An Astro integration that generates `.md` companion files and an `llms.txt` index from your built HTML pages. The `.md` files are Markdown versions of your HTML content, suitable for consumption by LLMs or static site search tools. Instead of using the raw source Markdown, this integration reverse engineers Markdown based on the generated HTML pages to avoid losing content declared in components and included files.

Current version: **1.0.0** --[npm](https://www.npmjs.com/package/astro-better-gen-markdown-pages)

## Installation

```shell-session
$ npm install astro-better-gen-markdown-pages
```

## Setup

In `astro.config.ts`:

```typescript
import genMarkdownPages from 'astro-better-gen-markdown-pages';

export default defineConfig({
  integrations: [
    genMarkdownPages({
      llmsTxtTitle: 'My Site Documentation',
      llmsTxtDescription: 'Complete docs for My Site.',
      trimTitleSuffix: ' | My Site',
    }),
  ],
});
```

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `llmsTxtTitle` | `string` | `'Documentation'` | Title in the generated `llms.txt` |
| `llmsTxtDescription` | `string` | `''` | Description in the generated `llms.txt` |
| `llmsTxtPath` | `string` | `'llms.txt'` | Output path for `llms.txt` |
| `trimTitleSuffix` | `string` | `''` | Strip this suffix from page titles in the index |
| `pageFilter` | `(path) => boolean` | `null` | Filter which pages get `.md` files |
| `indexFilter` | `(path) => boolean` | `() => true` | Filter which pages appear in `llms.txt` |
| `categorize` | `(path) => string` | first path segment | Group pages in `llms.txt` by category |
| `docsIndexUrl` | `string` | `''` | URL to add as the docs index reference in `llms.txt` |

## Output

After `astro build`:

*   Each HTML page gets a sibling `.md` file at the same path (e.g., `/docs/intro.md`)
*   A top-level `llms.txt` index lists all pages grouped by category

### llms.txt format

```plaintext
# My Site Documentation

> Complete docs for My Site.

## Getting Started

- [Introduction](https://better-static-sites.github.io/docs/intro.md): The basics.
- [Installation](https://better-static-sites.github.io/docs/install.md): How to install.

## Reference

- [API Reference](https://better-static-sites.github.io/docs/api.md): Full API docs.
```

## MarkdownOnly component

`MarkdownOnly` renders content that is invisible in the browser but included in the generated `.md` output. Use it to add LLM-facing context without cluttering the visual page.

```jsx
import MarkdownOnly from 'astro-better-gen-markdown-pages/MarkdownOnly.astro';

<MarkdownOnly>
  This text appears only in the generated .md file, not in the browser.
</MarkdownOnly>
```

## How it works

The integration hooks into `astro:build:done`. For each `.html` file in the output, it runs a Turndown-based HTML-to-Markdown conversion, then writes the `.md` file. The `llms.txt` is generated from the collected titles and paths.