Config

The lightfast.yml file controls what gets indexed from your repository and how Lightfast organizes your engineering knowledge. This guide covers all configuration options and best practices.

Quick Start

Get started with the minimal configuration:

yaml
version: 1
include:
  - "docs/**/*.md"
version: 1
include:
  - "docs/**/*.md"

That's it! This config will index all Markdown files in your docs/ directory.

Config File Location

Place your lightfast.yml file in the root directory of your repository. Lightfast automatically detects this file when your repository is connected and uses it to determine what to index.

bash
your-repository/
├── lightfast.yml          # Configuration file
├── README.md
├── docs/
│   ├── api/
│   └── guides/
└── src/
your-repository/
├── lightfast.yml          # Configuration file
├── README.md
├── docs/
│   ├── api/
│   └── guides/
└── src/

Core Concepts

version (required)

The configuration version. Currently only version 1 is supported.

yaml
version: 1
version: 1

include (required)

Array of glob patterns matching files to index. Patterns are relative to your repository root and use standard glob syntax.

Glob Pattern Syntax:

• * - Matches any characters except /
• ** - Matches any characters including / (recursive)
• ? - Matches any single character except /
• [abc] - Matches any character in the set

yaml
include:
  - "README.md"              # Specific file
  - "docs/**/*.md"           # All .md files in docs/ recursively
  - "**/*.mdx"               # All .mdx files anywhere
  - "rfcs/**/*"              # All files in rfcs/ directory
  - "guides/*.{md,mdx}"      # .md and .mdx files in guides/
  - "src/**/*.tsx"           # All TypeScript React files
include:
  - "README.md"              # Specific file
  - "docs/**/*.md"           # All .md files in docs/ recursively
  - "**/*.mdx"               # All .mdx files anywhere
  - "rfcs/**/*"              # All files in rfcs/ directory
  - "guides/*.{md,mdx}"      # .md and .mdx files in guides/
  - "src/**/*.tsx"           # All TypeScript React files

Best Practices:

• Use specific patterns to avoid indexing unnecessary files
• Start with documentation files (.md, .mdx, .txt)
• Consider including design documents and RFCs
• Test patterns locally before committing

Configuration Reference

Quick reference for all available options:

Automatic Exclusions: node_modules/, .git/, dist/, build/, .next/, .turbo/, dotfiles

Pattern Selection Guide

Choose the right patterns for your use case:

Documentation Sites

Use when: You have a dedicated docs folder with Markdown/MDX files

yaml
version: 1
include:
  - "docs/**/*.md"
  - "docs/**/*.mdx"
  - "README.md"
version: 1
include:
  - "docs/**/*.md"
  - "docs/**/*.mdx"
  - "README.md"

Engineering Wikis

Use when: You maintain design docs, RFCs, and runbooks

yaml
version: 1
include:
  - "wiki/**/*.md"
  - "rfcs/**/*.md"
  - "adrs/**/*.md"
  - "runbooks/**/*.md"
version: 1
include:
  - "wiki/**/*.md"
  - "rfcs/**/*.md"
  - "adrs/**/*.md"
  - "runbooks/**/*.md"

API Documentation

Use when: You have OpenAPI specs and API reference docs

yaml
version: 1
include:
  - "api/**/*.md"
  - "openapi.yaml"
  - "swagger.json"
  - "README.md"
version: 1
include:
  - "api/**/*.md"
  - "openapi.yaml"
  - "swagger.json"
  - "README.md"

Monorepo Documentation

Use when: Each package has its own documentation

yaml
version: 1
include:
  - "README.md"
  - "docs/**/*.md"
  - "packages/*/README.md"
  - "apps/*/README.md"
version: 1
include:
  - "README.md"
  - "docs/**/*.md"
  - "packages/*/README.md"
  - "apps/*/README.md"

Warning: Large codebases with many source files may hit indexing limits. Start with documentation files and expand as needed.

Validation and Errors

Lightfast validates your configuration when indexing starts. Common errors:

No Include Patterns

Fix: Add at least one glob pattern to the include array.

Invalid Glob Pattern

Fix: Use relative paths from repository root (e.g., docs/*.md instead of /docs/*.md or C:\docs\*.md).

Testing Your Configuration

Before committing, test your glob patterns locally:

bash
# Install fast-glob globally
npm install -g fast-glob-cli

# Test your patterns
fast-glob "docs/**/*.md" "**/*.mdx" --cwd /path/to/repo
# Install fast-glob globally
npm install -g fast-glob-cli

# Test your patterns
fast-glob "docs/**/*.md" "**/*.mdx" --cwd /path/to/repo

This shows which files will be matched by your patterns.

Updating Configuration

To update your configuration:

1. Edit lightfast.yml in your repository
2. Commit and push changes
3. Lightfast automatically detects updates and re-indexes

bash
git add lightfast.yml
git commit -m "Update Lightfast configuration"
git push origin main
git add lightfast.yml
git commit -m "Update Lightfast configuration"
git push origin main

Changes take effect within minutes. Previous indexed content from removed patterns will be automatically cleaned up.

Complete Example

Full configuration with all available options:

yaml
# Lightfast Configuration
# Full example with all options

version: 1

# Include patterns (required - at least one)
include:
  # Documentation
  - "README.md"
  - "docs/**/*.md"
  - "docs/**/*.mdx"

  # Design documents
  - "rfcs/**/*.md"
  - "adrs/**/*.md"

  # API documentation
  - "api-docs/**/*.json"
  - "openapi.yaml"

  # Code documentation
  - "src/**/*.tsx"
  - "packages/*/README.md"
# Lightfast Configuration
# Full example with all options

version: 1

# Include patterns (required - at least one)
include:
  # Documentation
  - "README.md"
  - "docs/**/*.md"
  - "docs/**/*.mdx"

  # Design documents
  - "rfcs/**/*.md"
  - "adrs/**/*.md"

  # API documentation
  - "api-docs/**/*.json"
  - "openapi.yaml"

  # Code documentation
  - "src/**/*.tsx"
  - "packages/*/README.md"

What's Next?

• Quickstart - Index your first repository
• Core Concepts - Understand how Lightfast works
• Authentication - Use the API in your apps