Search

Trellis Docs includes two search-related features out of the box: smart search for full-text documentation search and FAQ indexing for structured question navigation.

Smart search

The smart search plugin indexes all documentation at build time and provides fast, client-side search using Fuse.js. No external search service (like Algolia) is required.

How it works

1. Build time — the plugin scans all documentation files, extracts titles, headings, descriptions, keywords, and content.
2. Index generation — a searchIndex.json file is written to the public/ directory.
3. Client side — the search UI loads the index and uses Fuse.js for fuzzy matching with configurable field weights.

Configuration

['smart-search-plugin', {
  // Folders to exclude from indexing
  excludedFolders: ['includes', '_includes'],

  // File prefixes to exclude (e.g., _partial.mdx)
  excludedPrefixes: ['_'],

  // Field weights for search relevance (0.0 to 1.0)
  searchWeights: {
    title: 1.0,              // Page title — highest weight
    'sections.heading': 1.0, // Section headings — highest weight
    keywords: 0.8,           // Frontmatter keywords
    description: 0.6,        // Frontmatter description
    'sections.content': 0.5, // Section body content
    content: 0.4,            // Full page content — lowest weight
  },
}]

Search weights

Weights control how much each field contributes to search relevance. A weight of 1.0 means the field has maximum influence; 0.0 excludes it entirely.

Excluded content

Files are excluded from indexing if:

• They are in a folder listed in excludedFolders.
• Their filename starts with a prefix in excludedPrefixes.

Adding keywords

Add a keywords array to your frontmatter to improve search discoverability:

---
title: Smart Search
keywords: [search, fuse.js, indexing, full-text]
---

Keywords are weighted at 0.8 by default — higher than content but lower than titles. Use them for synonyms or terms that don't appear in the page text.

Search UI

The search interface is provided by the CustomSearch component in components/custom/CustomSearch/. It renders as a search icon in the navbar that opens a modal with:

• Text input with instant results
• Highlighted matching text
• Section-level results (not just page-level)
• Keyboard navigation support

FAQ index

The FAQ index plugin scans your FAQ directory for ### headings, treats each one as a question, and exposes the data so the FaqTableOfContents component can render a searchable, filterable question list.

How it works

1. Scans all MDX and .md files in the configured FAQ directory (excluding index.mdx)
2. Extracts ### headings from each file as questions
3. Generates anchor links from the heading text
4. Exposes the data so any component can consume it

Configuration

['./packages/faq-index-plugin', {
  faqDir: 'content/docs/faq',       // Directory containing FAQ files
  basePermalink: '/faq',    // Base URL for FAQ pages
}]

Writing FAQ pages

Each FAQ page is a standard MDX file in the content/docs/faq/ directory. Use ### headings for questions:

---
title: General
description: General questions about the framework.
---

### What is {vars.productName}?

{vars.productName} is an opinionated documentation framework built on {vars.frameworkName}...

### How do I customize the colors?

Edit `design-tokens.json` at the project root...

The plugin extracts each ### heading as a question and generates an anchor from the text:

• ### What is {vars.productName}? → anchor: what-is-trellis
• ### How do I customize the colors? → anchor: how-do-i-customize-the-colors

FaqTableOfContents component

The companion component renders the indexed questions as a searchable list. Use it on your FAQ index page:

---
title: Frequently Asked Questions
slug: /faq
hide_table_of_contents: true
---

Common questions about the framework.

<FaqTableOfContents />

The component:

• Groups questions by FAQ page (topic)
• Provides a text filter for searching across all questions
• Links each question directly to its anchor on the source page