rllmdoc

Overview

rllmdoc generates spec-compliant llms.txt and llms-full.txt files for your projects. It works with both Quarto website projects and R packages (pkgdown). The same functions handle both — you don’t need to know or care about the internals.

# Install
pak::pak("artalytics/rllmdoc")

Architecture and design choice

rllmdoc uses a hybrid model rather than treating native llms.txt output as the final artifact:

• Quarto and pkgdown still do useful work: Quarto llms-txt: true produces .llms.md files and pkgdown build_llm_docs() produces .md companion files.
• rllmdoc uses those supporting markdown files as inputs when assembling llms-full.txt.
• rllmdoc still writes the final llms.txt itself so the tracked artifact has curated grouping, per-entry descriptions, and strict spec validation.
• rllmdoc mirrors llms-only artifacts into _llms/ so local agents can load the same companion files and final indexes without depending on the site output directory.

This split is intentional. Native llms.txt generation is useful for markdown companions, but it is not the canonical final index for this package’s workflow.

Why this decision was made

We chose this design for three practical reasons:

• Spec reliability: rllmdoc can enforce strict llms.txt contract checks on the final tracked file rather than trusting tool-specific defaults.
• Consistent structure across project types: Quarto and pkgdown produce different native outputs; generating the final index in rllmdoc keeps a single predictable shape and grouping model.
• Controlled, reviewable artifact: the final llms.txt in-repo is produced by one deterministic code path, so changes are easier to reason about in tests, history, and code review.

Initialize a project

Run use_llm_docs() once at the root of any supported project:

rllmdoc::use_llm_docs()

This auto-detects the project type and configures it:

• Quarto website projects: adds llms-txt: true to _quarto.yml, enabling native .llms.md generation alongside HTML pages.
• Quarto book projects: no config changes needed; rllmdoc generates companion markdown from source chapters when native .llms.md files are not produced by the render.
• R packages: no configuration changes are currently required.

No other configuration is needed. Grouping and descriptions are derived from your existing project structure (_quarto.yml navbar/sidebar for websites, book.chapters/book.appendices for books, _pkgdown.yml reference sections for R packages).

Generate llms documentation

After initialization, generate everything with one call:

rllmdoc::llms_document()

This:

1. Validates your project structure and frontmatter
2. Ensures native companion markdown exists for the project type
3. Replaces native llms.txt with a curated llms.txt with H2 sections and per-entry descriptions
4. Generates llms-full.txt with full concatenated content
5. Mirrors llms-only artifacts into root _llms/

If the project is already configured and native outputs already exist, rebuild just the final llms artifacts with:

rllmdoc::build_llms_docs(".")

Convert an existing project

For projects that already have rendered output but haven’t used rllmdoc before:

# 1. Initialize
rllmdoc::use_llm_docs()

# 2. Ensure every .qmd has title + description in frontmatter
# rllmdoc will tell you exactly which files are missing fields

# 3. Generate
rllmdoc::llms_document()

If you have existing .md files that need frontmatter added before converting to .qmd:

rllmdoc::md2qmd(
  input = "docs/guide.md",
  yaml_defaults = list(
    title = "Guide",
    description = "How to use the platform."
  )
)

Validate without generating

To check your project is ready without actually rendering or writing files:

# Single file frontmatter check
rllmdoc::check_quarto_yaml("docs/guide.qmd")

All checks fail fast with the exact file and field that needs fixing.

Generate artifacts without rendering

If rendering is handled separately, generate both artifacts directly:

rllmdoc::build_llms_docs()

build_llms_docs() does not perform setup. It assumes the project is already configured for rllmdoc, but it can still ensure the native companion markdown exists before replacing site-local llms.txt and refreshing _llms/.

Wire into CI

For Quarto projects, call rllmdoc after your site render step:

rllmdoc::build_llms_docs(".")

For R packages, call after pkgdown::build_site() in your CI workflow:

rllmdoc::build_llms_docs(".")

In both cases, install rllmdoc in CI with:

pak::pak("artalytics/rllmdoc")

Frontmatter requirements

Every .qmd file included in your project’s render list must have at minimum:

---
title: "Document Title"
description: "One-line summary of what this document covers."
---

rllmdoc uses title for the link text and description for the entry annotation in llms.txt. Missing either field is a hard error — see vignette("spec-contract") for the full failure mode reference.

Advanced usage patterns

Extract frontmatter programmatically

fm <- rllmdoc::parse_quarto_yaml("docs/guide.qmd")
fm$title
#> [1] "Guide"
fm$description
#> [1] "How to use the platform."

Read document body without frontmatter

body <- rllmdoc::parse_quarto_body("docs/guide.qmd")
# Returns the content after the --- frontmatter block