Config

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

Quick Start

Get started with the minimal configuration:

1version: 1
2store: my-docs
3include:
4- "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.

1your-repository/
2├── lightfast.yml          # Configuration file
3├── README.md
4├── docs/
5│   ├── api/
6│   └── guides/
7└── src/

Core Concepts

version (required)

The configuration version. Currently only version 1 is supported.

1version: 1

store (required)

A unique identifier for this documentation set within your workspace. Store names help organize knowledge across multiple repositories.

Constraints:

• Must not be empty
• Maximum 20 characters
• Lowercase alphanumeric characters and hyphens only
• No leading, trailing, or consecutive hyphens

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

1include:
2- "README.md"              # Specific file
3- "docs/**/*.md"           # All .md files in docs/ recursively
4- "**/*.mdx"               # All .mdx files anywhere
5- "rfcs/**/*"              # All files in rfcs/ directory
6- "guides/*.{md,mdx}"      # .md and .mdx files in guides/
7- "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

1version: 1
2store: docs
3include:
4- "docs/**/*.md"
5- "docs/**/*.mdx"
6- "README.md"

Engineering Wikis

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

1version: 1
2store: eng-wiki
3include:
4- "wiki/**/*.md"
5- "rfcs/**/*.md"
6- "adrs/**/*.md"
7- "runbooks/**/*.md"

API Documentation

Use when: You have OpenAPI specs and API reference docs

1version: 1
2store: api-docs
3include:
4- "api/**/*.md"
5- "openapi.yaml"
6- "swagger.json"
7- "README.md"

Monorepo Documentation

Use when: Each package has its own documentation

1version: 1
2store: monorepo-docs
3include:
4- "README.md"
5- "docs/**/*.md"
6- "packages/*/README.md"
7- "apps/*/README.md"

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

Multi-Repository Setup

If your organization has multiple repositories, use unique store names to organize knowledge:

Documentation Repository

1version: 1
2store: docs-site
3include:
4- "**/*.md"
5- "**/*.mdx"

API Repository

1version: 1
2store: api-service
3include:
4- "README.md"
5- "docs/**/*.md"
6- "openapi.yaml"

Infrastructure Repository

1version: 1
2store: infra-wiki
3include:
4- "README.md"
5- "runbooks/**/*.md"
6- "terraform/**/*.md"

Then filter searches by store:

• Search store:docs-site for product documentation
• Search store:api-service for API references
• Search store:infra-wiki for infrastructure guides

Validation and Errors

Lightfast validates your configuration when indexing starts. Common errors:

Invalid Store Name

Fix: Use a valid store name following the constraints.

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:

1# Install fast-glob globally
2npm install -g fast-glob-cli
3
4# Test your patterns
5fast-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

1git add lightfast.yml
2git commit -m "Update Lightfast configuration"
3git 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:

1# Lightfast Configuration
2# Full example with all options
3
4version: 1
5
6# Store name (required - unique per workspace)
7store: platform-docs
8
9# Include patterns (required - at least one)
10include:
11# Documentation
12- "README.md"
13- "docs/**/*.md"
14- "docs/**/*.mdx"
15
16# Design documents
17- "rfcs/**/*.md"
18- "adrs/**/*.md"
19
20# API documentation
21- "api-docs/**/*.json"
22- "openapi.yaml"
23
24# Code documentation
25- "src/**/*.tsx"
26- "packages/*/README.md"

What's Next?

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