builder library

Build-time indexer for jaspr_search.

Walks a content directory, splits each markdown page on its headings, and produces the SearchDoc list that becomes search-index.json — the payload the client-side search dialog fetches and scores in the browser.

Import this from a tool/build_search_index.dart script, never from anything also compiled for the web: it uses dart:io.

void main(List<String> args) async {
  final build = await buildSearchIndex(
    Directory('content'),
    groupFor: (route) => sectionOf(route)?.title ?? '',
  );
  final output = File('web/search-index.json');

  if (args.contains('--check')) {
    if (!searchIndexIsCurrent(build, output)) {
      stderr.writeln('web/search-index.json is stale.');
      exit(1);
    }
    return;
  }
  writeSearchIndex(build, output);
}

Classes

SearchDoc

One page in the index.

SearchHit

A scored result row, produced by searchIndex.

SearchIndexBuild

The result of walking a content directory: the indexed docs, plus the exact JSON that would be written for them.

SearchSection

One heading-delimited chunk of a page.

Functions

anchorFor(String rawHeading) → String

Reproduces the heading id that package:markdown's HeaderWithIdSyntax generates, so a search result can deep-link to #anchor.

buildSearchIndex(Directory contentDir, {String routeOf(File file, String contentPath)?, String groupFor(String route)?, String titleFor(String route, Map<String, String> frontMatter)?, String descriptionFor(String route, Map<String, String> frontMatter)?, int compare(SearchDoc a, SearchDoc b)?, int maxSectionLength = 1200}) → Future<SearchIndexBuild>

Walks contentDir for .md files and builds a SearchIndexBuild.

plainText(String markdown) → String

Reduces markdown to searchable prose.

routeFor(String path, String contentPath) → String

content/operations/streaming.md -> /operations/streaming.

searchIndexIsCurrent(SearchIndexBuild build, File output) → bool

Whether output already holds exactly build's JSON.

sectionsOf(String body, {int maxSectionLength = 1200}) → List<Map<String, Object?>>

Splits a markdown body into {h: heading, a: anchor, b: body} records.

splitFrontMatter(String raw) → ({String body, Map<String, String> frontMatter})

Splits leading --- YAML front matter from the markdown body.

writeSearchIndex(SearchIndexBuild build, File output) → void

Writes build's JSON to output, creating parent directories as needed.

Exceptions / Errors

ContentDirectoryNotFoundException

Thrown by buildSearchIndex when the given content directory doesn't exist. A plain Exception, not an ArgumentError: a missing directory is an expected, recoverable condition for a CLI or script to catch and report — not a programmer bug.