README.md

@mdream/action

GitHub Action that processes prerendered HTML files into llms.txt artifacts for CI/CD workflows.

Setup

Add the action to any workflow step after your site build completes. Requires Node.js to be available in the runner environment.

- uses: harlan-zw/mdream@v1
  with:
    glob: 'dist/**/*.html'
    site-name: My Documentation
    description: Technical documentation and guides
    origin: 'https://mydocs.com'

Usage

Basic

- name: Generate llms.txt artifacts
  uses: harlan-zw/mdream@v1
  with:
    glob: 'dist/**/*.html'
    site-name: My Documentation
    description: Technical documentation and guides
    origin: 'https://mydocs.com'

Generates llms.txt, llms-full.txt, and a md/ directory in the current working directory.

Full Workflow

name: Generate LLMs.txt

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  generate-llms-txt:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '24'

      - name: Install dependencies
        run: npm ci

      - name: Build documentation
        run: npm run build

      - name: Generate llms.txt artifacts
        id: llms
        uses: harlan-zw/mdream@v1
        with:
          glob: 'dist/**/*.html'
          site-name: My Documentation
          description: Technical documentation and guides
          origin: 'https://mydocs.com'
          output: dist

      - name: Upload llms.txt artifacts
        uses: actions/upload-artifact@v4
        with:
          name: llms-txt-artifacts
          path: |
            dist/llms.txt
            dist/llms-full.txt
            dist/md/

      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/main'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./dist

Using Outputs

Reference the action outputs in subsequent steps:

- name: Generate llms.txt artifacts
  id: llms
  uses: harlan-zw/mdream@v1
  with:
    glob: 'dist/**/*.html'
    site-name: My Docs
    description: My documentation site
    origin: 'https://mydocs.com'
    output: dist

- name: Print generated file paths
  run: |
    echo "llms.txt: ${{ steps.llms.outputs.llms-txt-path }}"
    echo "llms-full.txt: ${{ steps.llms.outputs.llms-full-txt-path }}"
    echo "Markdown files: ${{ steps.llms.outputs.markdown-files }}"

Verbose Logging

- name: Generate llms.txt artifacts
  uses: harlan-zw/mdream@v1
  with:
    glob: 'dist/**/*.html'
    site-name: My Docs
    description: My documentation site
    origin: 'https://mydocs.com'
    verbose: 'true'

API Reference

Inputs

Input	Required	Default	Description
glob	Yes		Glob pattern to match HTML files (e.g., dist/**/*.html).
site-name	Yes		Name of your site. Used as the heading in generated files.
description	Yes		Description of your site content. Rendered as a blockquote below the site name.
origin	Yes		Base URL of your site (e.g., https://mysite.com). Used to construct full page URLs.
output	No	.	Output directory for generated files. Created recursively if it does not exist.
chunk-size	No	4096	Chunk size for streaming processing.
verbose	No	false	Enable verbose logging. Prints configuration values to the action log.

Outputs

Output	Description
llms-txt-path	Path to the generated llms.txt file.
llms-full-txt-path	Path to the generated llms-full.txt file.
markdown-files	JSON array of paths to all generated individual Markdown files.

Generated Files

File	Description
llms.txt	Index listing all pages with titles, URLs, and descriptions.
llms-full.txt	Full Markdown content of every page with YAML frontmatter and a table of contents.
md/<path>.md	Individual Markdown files mirroring the site URL hierarchy.

URL Path Resolution

HTML file paths are converted to URL paths automatically:

File Path	Resolved URL
dist/index.html	/
dist/about.html	/about
dist/docs/getting-started.html	/docs/getting-started
dist/blog/2024/post.html	/blog/2024/post

The .html extension is stripped. index.html files resolve to their parent directory path. The origin input is prepended to construct full URLs in the output.

Metadata Extraction

Metadata is extracted from each HTML file in the following priority order:

Title: <title> tag, then <meta property="og:title">. Description: <meta name="description">, then <meta property="og:description">.

Descriptions are truncated to 100 characters in the llms.txt listing. Full metadata is embedded as YAML frontmatter in llms-full.txt.

License

MIT