6.7 KiB

Raw Permalink Blame History

llms.txt Generation System

This directory contains Hugo templates for automatically generating llms.txt files following the llmstxt.org specification.

Overview

The llms.txt format helps LLMs discover and understand documentation structure. Hugo automatically generates these files during the build process.

Template Files

`index.llms.txt`

Location: /layouts/index.llms.txt
Output: /llms.txt (site-level)
Type: Hugo template
Purpose: Primary entry point for LLM discovery
Content: Dynamically generated from data/products.yml with:
- Product descriptions from data files
- Organized by product category
- Conditional rendering for optional products

`section.llms.txt`

Location: /layouts/_default/section.llms.txt
Output: Product/section-level llms.txt files (e.g., /influxdb3/core/llms.txt)
Type: Hugo template
Purpose: Provide curated navigation for specific products/sections
Content: Dynamically generated from:
- Product metadata from data/products.yml
- Section content and child pages
- Page descriptions

Hugo Configuration

In config/_default/hugo.yml:

outputFormats:
  llmstxt:
    mediaType: text/plain
    baseName: llms
    isPlainText: true
    notAlternative: true
    permalinkable: true
    suffixes:
      - txt

outputs:
  section:
    - HTML
    - llmstxt  # Generates llms.txt for all sections
  home:
    - HTML
    - llmstxt  # Generates root /llms.txt

Generated Files

After building with hugo:

public/
├── llms.txt                              # Site-level discovery file
├── influxdb3/
│   ├── core/
│   │   ├── llms.txt                      # InfluxDB 3 Core product index
│   │   ├── get-started/
│   │   │   └── llms.txt                  # Section-level index
│   │   └── query-data/
│   │       └── llms.txt                  # Section-level index
│   ├── cloud-dedicated/
│   │   └── llms.txt                      # Cloud Dedicated product index
│   └── cloud-serverless/
│       └── llms.txt                      # Cloud Serverless product index
├── telegraf/
│   └── v1/
│       └── llms.txt                      # Telegraf product index
└── flux/
    └── v0/
        └── llms.txt                      # Flux product index

llmstxt.org Specification Compliance

Required Elements

✅ H1 header: Product or section name
✅ Curated links: Not exhaustive - intentionally selective

Optional Elements

✅ Blockquote summary: Brief product/section description
✅ Content paragraphs: Additional context (NO headings allowed)
✅ H2-delimited sections: Organize links by category
✅ Link format: [Title](url): Description

Key Rules

H1 is required - Only the product/section name
Content sections cannot have headings - Use paragraphs only
Curate, don't list everything - Be selective with links
Use relative URLs - LLMs resolve them in context
"Optional" section - Signals skippable secondary content

Customizing llms.txt Files

For Site-Level (/llms.txt)

Edit /layouts/index.llms.txt directly. This file is hardcoded for precise curation of top-level products.

For Product/Section-Level

The /layouts/_default/section.llms.txt template automatically generates llms.txt files for all sections.

To customize a specific product's llms.txt:

Create a product-specific template following Hugo's lookup order:

layouts/influxdb3/core/section.llms.txt  # Specific to Core
layouts/influxdb3/section.llms.txt       # All InfluxDB 3 products
layouts/_default/section.llms.txt        # Default for all

Example: Custom template for InfluxDB 3 Core

Create /layouts/influxdb3/core/section.llms.txt:

# InfluxDB 3 Core

> InfluxDB 3 Core is the open source, high-performance time series database.

{{- /* Custom curated sections */ -}}

## Getting Started

- [Install InfluxDB 3 Core](/influxdb3/core/install/): Installation guide
- [Quick start](/influxdb3/core/get-started/): Get started in 5 minutes

## Guides

- [Write data](/influxdb3/core/write-data/): Write data guide
- [Query with SQL](/influxdb3/core/query-data/sql/): SQL query guide

Using Product Metadata from data/products.yml

The template accesses product metadata:

{{- $product := index .Site.Data.products "influxdb3_core" -}}
{{- $productName := $product.name -}}           {{/* "InfluxDB 3 Core" */}}
{{- $productAltname := $product.altname -}}     {{/* Alternative name */}}
{{- $productVersion := $product.latest -}}      {{/* "core" */}}

Testing llms.txt Files

Build and Check Output

# Build Hugo site
./node_modules/.bin/hugo --quiet

# Check generated llms.txt files
ls -la public/llms.txt
ls -la public/influxdb3/core/llms.txt

# View content
cat public/llms.txt
cat public/influxdb3/core/llms.txt

Validate Against Specification

Check that generated files follow llmstxt.org spec:

✅ Starts with single H1 header
✅ Optional blockquote summary after H1
✅ Content sections have NO headings
✅ H2 sections organize curated links
✅ Link format: [Title](url): Description
✅ Relative URLs work correctly

Test LLM Discovery

# Test with curl (simulates LLM access)
curl https://docs.influxdata.com/llms.txt
curl https://docs.influxdata.com/influxdb3/core/llms.txt

# Verify content type
curl -I https://docs.influxdata.com/llms.txt
# Should return: Content-Type: text/plain

Build Process

llms.txt files are automatically generated during:

Local development: hugo server regenerates on file changes
Production build: hugo --quiet generates all llms.txt files
CI/CD: Build pipeline includes llms.txt generation

Maintenance

Adding a New Product

Add product metadata to data/products.yml
llms.txt will auto-generate using section.llms.txt template
Optionally create custom template in layouts/<product>/section.llms.txt

Updating Site-Level llms.txt

Edit /layouts/index.llms.txt to add/remove product links.

Troubleshooting

Problem: llms.txt file not generated Solution: Check that output format is configured in config/_default/hugo.yml

Problem: Content includes HTML tags Solution: Use | plainify filter in template

Problem: URLs are absolute instead of relative Solution: Use .RelPermalink instead of .Permalink

6.7 KiB Raw Permalink Blame History