Configuration

The theme is registered as an Eleventy plugin in eleventy.config.js. The call takes the eleventyConfig object and an options object, and returns the Eleventy configuration:

import apidocs from "@carrotsearch/eleventy-apidocs";

export default async function (eleventyConfig) {
  return apidocs(eleventyConfig, {
    contentDir: "src/content"
  });
}

Every option is optional — paths default to conventional locations under src/, and the rest fall back to sensible defaults. The sections below describe each one in full. For the minimal set most sites start with, see Getting started.

Content and layout

Where the theme reads your pages and the shared layout fragments from.

contentDir: Directory of article HTML files, relative to the project root. Default: src/content.
navigation: Path to the navigation manifest, either a flat array of articles or a chaptered shape. Default: src/navigation.json. See Navigation for the manifest format.
logo: Path to an HTML fragment rendered in the header's logo slot. Default: src/logo.html.
footer: Path to an HTML fragment rendered in the page footer. Default: src/footer.html.
head: Path to an HTML fragment appended to the document <head> on every page — use it for site-wide <meta> tags (description, Open Graph, Twitter cards), favicons, or analytics snippets. Default: src/head.html. A missing file renders as nothing.
variables: Map of $NAME$ placeholders to replacement values. Each placeholder is replaced with its value across every page, including layout markup such as the header and footer. Default: {}. See Variables for details.

Code highlighting

codeThemes: Shiki themes used to syntax-highlight code blocks, as an object with light and dark keys. Either key may be overridden on its own; the other keeps its default. Values are Shiki theme names (e.g. nord, vitesse-dark) or a custom TextMate theme object. Default: { light: "github-light", dark: "github-dark" }.

Search

Tune how search results are ordered and capped. The defaults work without configuration; reach for these when a site has many API symbols to prioritize. See Search for the full picture.

apiKindOrder: Array of data-api-kind values that sort to the front of the API group in search results. Listed kinds appear in this order; each kind’s hits stay ranked by relevance among themselves, and any unlisted kind follows. Use it to surface a site’s primary API concepts — say ["stage", "component"] — ahead of incidental ones. The ordering reshuffles only the results already shown, so it never displaces a stronger match. Default: [] (relevance order only).
searchLimits: Caps on how many search results each group shows. Three reserved keys set per-group totals — api, sections and pages (default 8 each). Any other key is a data-api-kind sub-cap inside the API group: it limits how many hits of that kind appear, bounded by the api total, while kinds you don’t list stay capped only by that total. For example { api: 6, endpoint: 3 } shows at most six API hits, no more than three of them endpoints. Selection stays relevance-ordered, with apiKindOrder applied after. Default: {} (the built-in defaults above).
searchFetchLimit: Size of the candidate pool considered before results are sorted into the API and Sections groups. Raise it if larger searchLimits totals need a deeper pool to fill from. Default: 32.

Link checking

linkCheck

After a full build, crawl the generated site for broken links — both 404s and in-page #anchor targets that don't exist — and fail the build if any are found. Runs only on full builds, never under --serve. Default: true.

Pass false to disable the check entirely, or an object with any of the following fields:

external: Also check external (off-site) links. Off by default, so a third-party site being slow or down can't break your build. Default: false.
skip: Array of regular-expression strings; a link whose URL matches any of them is not checked. Default: [].
fatal: Throw on broken links, failing the build. Set false to report them without failing. Default: true.
concurrency: How many URLs the crawl fetches at once. Kept modest by default so the crawl can't overwhelm its own local server on a busy CI machine, which surfaces as false 404 reports for pages that exist. Default: 16.

Pipeline extensions

transformers: Custom passes that run on each article before the built-in passes. Use them to reshape authored markup into a shape the built-ins understand. Default: [].
finalizers: Custom passes that run on each article after the built-in passes, with access to the fully processed output. Default: [].

Both take an array of functions, each receiving a Cheerio instance to mutate in place. See Pipeline extensions for the pass signature, the per-page context, and worked examples.