Utilities Reference

function parseMarkdown(
  input: string,
  options?: ParseOptions
): ContentData

interface ParseOptions {
  generateToc?: boolean;        // Default: true
  strictFrontmatter?: boolean;  // Default: false
}

interface ContentData {
  frontmatter: Record<string, any>;
  body: string;
  toc: TocEntry[];
}

import { parseMarkdown } from '@/lib/content';

const markdown = `---
title: "My Doc"
slug: "my-doc"
---

# Hello

This is content.`;

const parsed = parseMarkdown(markdown);
console.log(parsed.frontmatter.title); // "My Doc"
console.log(parsed.body); // "# Hello\n\nThis is content."
console.log(parsed.toc); // Array of headings

// Parse without TOC generation
const parsedNoToc = parseMarkdown(markdown, { generateToc: false });

function generateSlug(text: string): string

import { generateSlug } from '@/lib/content';

generateSlug('Getting Started'); // "getting-started"
generateSlug('API & Reference'); // "api-and-reference"
generateSlug('Hello World!'); // "hello-world"

async function buildSearchIndex(docsPath: string): Promise<SearchIndex>

import { buildSearchIndex, saveIndexToFile } from '@/lib/search';

const index = await buildSearchIndex('./docs');
await saveIndexToFile('./public/search-index.json', index);

interface SearchIndex {
  documents: Record<string, SearchDocument>;
  index?: any; // FlexSearch index (built client-side)
  metadata: {
    buildTime: number;
    documentCount: number;
    indexedWords: number;
  };
}

function querySearchIndex(
  index: SearchIndex,
  documents: Record<string, SearchDocument>,
  query: string,
  limit?: number
): SearchResult[]

import { querySearchIndex, buildSearchIndex } from '@/lib/search';

// Build index
const searchIndex = await buildSearchIndex('./docs');

// Search
const results = querySearchIndex(searchIndex, searchIndex.documents, "authentication", 10);

results.forEach(result => {
  console.log(result.title);    // Document title
  console.log(result.excerpt);  // Preview text
  console.log(result.path);     // URL path
  console.log(result.score);    // Relevance score
});

function serializeIndex(index: SearchIndex): string

function deserializeIndex(serialized: string): SearchIndex

import { serializeIndex, deserializeIndex, buildSearchIndex } from '@/lib/search';

// Build and serialize
const index = await buildSearchIndex('./docs');
const json = serializeIndex(index);

// Later, deserialize
const restored = deserializeIndex(json);

async function saveIndexToFile(
  filePath: string,
  index: SearchIndex
): Promise<void>

function discoverDocuments(
  rootPath: string,
  currentPath?: string,
  parentId?: string | null
): NavigationNode[]

import { discoverDocuments, buildNavigationTree } from '@/lib/navigation';

// Discover all documents
const nodes = discoverDocuments('./docs/examples');

// Build hierarchical tree
const { roots, nodeMap } = buildNavigationTree(nodes);

// Access nested document
const deepDoc = nodeMap['deep/nesting/many/levels/deep-doc'];
console.log(deepDoc.title); // Document title from frontmatter

function buildNavigationTree(nodes: NavigationNode[]): NavigationStructure

interface NavigationStructure {
  roots: NavigationNode[];
  nodeMap: Record<string, NavigationNode>;
  versions: Version[];
  currentVersion?: string;
}

function getBreadcrumbs(
  structure: NavigationStructure,
  pathname: string
): BreadcrumbItem[]

import { discoverDocuments, buildNavigationTree, getBreadcrumbs } from '@/lib/navigation';

const nodes = discoverDocuments('./docs');
const nav = buildNavigationTree(nodes);
const breadcrumbs = getBreadcrumbs(nav, '/docs/guides/advanced-features');

// Returns:
// [
//   { href: '/docs', label: 'Docs' },
//   { href: '/docs/guides', label: 'Guides' },
//   { href: '/docs/guides/advanced-features', label: 'Advanced Features' }
// ]

function findNodeByPath(
  structure: NavigationStructure,
  pathname: string
): NavigationNode | undefined

function detectVersions(baseDir?: string): Version[]

interface Version {
  tag: string;
  label: string;
  isCurrent: boolean;
}

import { detectVersions } from '@/lib/navigation';

const versions = detectVersions();
// Returns array of Git tag versions
// Example: [{ tag: 'v1.0.0', label: 'v1.0.0', isCurrent: true }]
// Falls back to [{ tag: 'main', label: 'Latest', isCurrent: true }] if no tags

function generateNavigation(
  docsPath?: string,
  baseDir?: string
): NavigationStructure

import { generateNavigation } from '@/lib/navigation';

const nav = generateNavigation('./docs/examples');
console.log(nav.roots); // Root navigation nodes
console.log(nav.nodeMap); // All nodes by ID
console.log(nav.versions); // Git tag versions

function flattenNavigation(nodes: NavigationNode[]): NavDocument[]

interface NavDocument {
  title: string;
  path: string;
}

import { flattenNavigation } from '@/lib/nav-helpers';

const flat = flattenNavigation(nav.roots);
flat.forEach(doc => {
  console.log(`${doc.title} -> ${doc.path}`);
});

interface DocumentMetadata {
  title: string;
  slug: string;
  author?: string;
  date?: string;
  tags?: string[];
  published?: boolean;
  order?: number;
}

interface ContentData {
  frontmatter: Record<string, any>;
  body: string;
  toc: TocEntry[];
}

interface SearchDocument {
  id: string;
  title: string;
  path: string;
  body: string;
  excerpt?: string;
  tags?: string[];
  headings?: string[];
}

interface SearchResult {
  id: string;
  title: string;
  path: string;
  excerpt: string;
  score: number;
  tags?: string[];
}

interface SearchIndex {
  documents: Record<string, SearchDocument>;
  index?: any; // FlexSearch index (built client-side)
  metadata: {
    buildTime: number;
    documentCount: number;
    indexedWords?: number;
  };
}

interface NavigationNode {
  id: string;
  title: string;
  path: string;
  type?: 'folder' | 'doc';
  parentId?: string | null;
  children?: NavigationNode[];
  frontmatter?: DocumentMetadata;
}

interface NavigationStructure {
  roots: NavigationNode[];
  nodeMap: Record<string, NavigationNode>;
  versions: Version[];
  currentVersion?: string;
}

interface Version {
  tag: string;
  label: string;
  isCurrent: boolean;
}

interface BreadcrumbItem {
  href: string;
  label: string;
}

function getPrevNextDocs(
  currentPath: string,
  navNodes: NavigationNode[]
): { prev?: NavDocument; next?: NavDocument }

import { getPrevNextDocs } from '@/lib/nav-helpers';

const { prev, next } = getPrevNextDocs('/docs/guides/advanced', nav.roots);
if (prev) console.log('Previous:', prev.title);
if (next) console.log('Next:', next.title);

async function highlightCode(code: string, language: string): Promise<string>

import { highlightCode } from '@/lib/highlight';

const html = await highlightCode('const x = 5;', 'typescript');
// Returns HTML with syntax highlighting

function extractExcerpt(
  text: string,
  query?: string,
  contextWords?: number
): string

import { extractExcerpt } from '@/lib/search';

const excerpt = extractExcerpt(longText, 'authentication', 2);
// Returns excerpt with query highlighted

function flattenToc(toc: TocEntry[]): TocEntry[]

import { parseMarkdown, flattenToc } from '@/lib/content';

const parsed = parseMarkdown(markdown);
const flatToc = flattenToc(parsed.toc);
// Returns all headings in flat array (no nesting)