Type to search.

↵ to open ↑↓ to navigate Esc to close

Getting started

Overview

@carrotsearch/eleventy-apidocs is an Eleventy plugin that turns a tree of authored HTML files into a navigable documentation site with shared layout, navigation, theme switching, code highlighting, responsive images, and a per-page table of contents.

Content is authored in plain HTML. The authoring surface is small — a handful of conventions on top of standard tags — so the source stays close to what eventually ships in the browser.

Install

Add Eleventy and the theme to your project:

pnpm add -D @11ty/eleventy
pnpm add @carrotsearch/eleventy-apidocs

Requirements

Node 20.11 or later is required. The plugin is published as ESM and expects an ESM consumer config.

Build scripts (pnpm and Bun)

pnpm and Bun don't run dependencies' install scripts by default. The theme needs sharp (responsive images) and esbuild (search bundling) built, so allow them after installing — otherwise image processing and search fail at build time. With pnpm, run pnpm approve-builds and allow both; with Bun, add them to trustedDependencies in package.json. npm and Yarn run these automatically and need nothing.

Configure Eleventy

In eleventy.config.js, register the plugin and point it at your content directory: 

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

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

Common options

Every option is optional — paths default to conventional locations under src/. The handful most sites set up front:

contentDir

Directory of article HTML files, relative to the project root. Default: src/content.

navigation

Path to the navigation manifest that orders the sidebar and prev/next links. Default: src/navigation.json.

Path to an HTML fragment rendered in the header's logo slot. Default: src/logo.html.

Path to an HTML fragment rendered in the page footer. Default: src/footer.html.

The plugin also takes options for the document head, build-time variables, code highlighting, search ordering, link checking, and custom pipeline passes. See the Configuration reference for the full list.

Authoring contract

Each article is a single HTML file. The expected outer shape is an <article> with an <h1> title and one or more <section> blocks. The first heading inside each section carries a stable id: 

<article>
  <h1>Title</h1>
  <section>
    <h2 id="intro">Intro</h2>
    <p>…</p>
    <section>
      <h3 id="intro:details">Details</h3>
      <p>…</p>
    </section>
  </section>
</article>

Heading ids anchor the per-page table of contents and act as stable deep links. Nested sections appear as nested ToC entries; by convention their ids carry the parent's id as a colon-separated prefix (intro:details), so each heading's id reads as a path from the page root.

Next steps

Browse the rest of the sample docs to see what the theme renders:

  • Code blocks — syntax highlighting, highlighted lines, embeds.

  • Images — responsive bitmaps, inline SVG, lightbox.