FairGarden Docs

Load Server Sitemap

The loadServerSitemap utility parses sitemap index files to load page metadata at runtime. It reads the sitemap index file, finds createSitemap factory calls, resolves page imports, and builds a complete Sitemap object with schema and data.

Tip

Use this function for runtime loading outside of Next.js builds (e.g., in tests, scripts, or non-Next.js applications).

Basic Usage

 
import { loadServerSitemap } from '@fairgarden/docs/pipeline/loadServerSitemap';

// Load sitemap from a sitemap index file
const sitemap = await loadServerSitemap('file:///app/sitemap/index.ts');

// Returns: { schema: {...}, data: { LibComponents: {...}, LibFunctions: {...} } }

The function:

  • Reads the sitemap index file
  • Finds the createSitemap() call and extracts page imports
  • Resolves each page import path to absolute file paths
  • Loads each page's markdown file and extracts metadata
  • Returns a Sitemap object with schema and data

Common Patterns

Loading from Sitemap Index

Given a sitemap index file:

// app/sitemap/index.ts
import { createSitemap } from '../functions/createSitemap';
import LibComponents from '../lib/components/page.mdx';
import LibFunctions from '../lib/functions/page.mdx';

export const sitemap = createSitemap(import.meta.url, {
  LibComponents,
  LibFunctions,
});

You can load it at runtime:

const sitemap = await loadServerSitemap('file:///path/to/app/sitemap/index.ts');

// Returns:
// {
//   schema: {
//     slug: 'string',
//     path: 'string',
//     title: 'string',
//     description: 'string',
//     sections: 'string[]',
//     subsections: 'string[]',
//     keywords: 'string[]',
//   },
//   data: {
//     LibComponents: {
//       title: 'Lib Components',
//       prefix: '/lib/components/',
//       pages: [...]
//     },
//     LibFunctions: {
//       title: 'Lib Functions',
//       prefix: '/lib/functions/',
//       pages: [...]
//     }
//   }
// }

Advanced Usage

Custom Implementation

Create a custom loadServerSitemap function using the factory:

import { createLoadServerSitemap } from '@fairgarden/docs/pipeline/loadServerSitemap';

const customLoadSitemap = createLoadServerSitemap({
  // Override the root context for resolving relative paths
  rootContext: '/custom/root/path',
});

const sitemap = await customLoadSitemap('file:///path/to/sitemap/index.ts');

Using with Orama search:

import { create, insertMultiple, search } from '@orama/orama';
import { loadServerSitemap } from '@fairgarden/docs/pipeline/loadServerSitemap';

// Load the sitemap at runtime
const sitemap = await loadServerSitemap('file:///app/sitemap/index.ts');

// Create search index with the schema
const searchIndex = await create({
  schema: sitemap.schema,
});

// Flatten and insert pages
const pages = Object.entries(sitemap.data).flatMap(([_key, section]) => {
  return section.pages.map((page) => ({
    ...page,
    section: section.title,
    prefix: section.prefix,
  }));
});

await insertMultiple(searchIndex, pages);

// Search
const results = await search(searchIndex, { term: 'code' });

Comparison: Build-Time vs Runtime
FeatureBuild-Time (Webpack Loader)Runtime (loadServerSitemap)
When processedDuring Next.js buildAt runtime when called
CachingWebpack dependency cacheManual caching via Map
EnvironmentNext.js onlyAny Node.js environment
Use caseProduction buildsTests, scripts, non-Next.js apps
PerformanceFastest (precomputed)Slower (reads files at runtime)

Types

loadServerSitemap

Default loadServerSitemap function that loads sitemap data from a sitemap index file. This function parses the sitemap index file to find createSitemap calls and resolves the page index paths from the imports.

ParameterTypeDescription
url
string
Return Type
Promise<Sitemap>

createLoadServerSitemap

Creates a loadServerSitemap function with custom options.

This factory function creates a LoadServerSitemap implementation that:

  1. Parses the sitemap index file to find createSitemap calls with page imports
  2. Resolves all page index paths from the imports
  3. Loads each page index using loadServerPageIndex
  4. Returns a Sitemap object with schema and page data
PropertyTypeDescription
rootContext
string | undefined

The root context directory for resolving relative paths. Defaults to the directory containing the sitemap index file.

Return Type

LoadServerSitemap function that takes a file URL and returns Promise<Sitemap>

createSitemapSchema

Creates the default Orama schema for search indexing. See: https://docs.orama.com/docs/orama-js/usage/create#schema-properties-and-types

Return Type
Record<string, OramaSchemaType>

Additional Types
CreateLoadServerSitemapOptions

Options for creating a loadServerSitemap function

type CreateLoadServerSitemapOptions = {
  /**
   * The root context directory for resolving relative paths.
   * Defaults to the directory containing the sitemap index file.
   */
  rootContext?: string;
}