# eleventy-apidocs

> An Eleventy plugin for HTML-first product documentation. Authored content is plain HTML, wrapped in a responsive shell with light/dark themes, syntax highlighting, a per-page table of contents, prose and API-symbol search, image processing, and View-Transition-driven navigation.

## Introduction

- [Getting started](/getting-started.md): @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.

## Authoring

- [Page structure](/page-structure.md): Each article is a single HTML file. The theme reads its structure from standard tags: <article> wraps the page, <section> wraps each topic, and id-bearing headings drive anchors, deep links, and the right-hand table of contents.
- [Code blocks](/code-blocks.md): Code blocks use the <pre data-language="..."> contract. Shiki provides dual-theme syntax highlighting.
- [Images](/images.md): The image pipeline rewrites raster <img> tags into a responsive <picture> with AVIF, WebP, and fallback sources, srcsets sized for the article width, and a tiny LQIP background that holds the aspect ratio while the picture loads. SVG files referenced by <img> are inlined into the document.
- [Callouts](/callouts.md): Three callout variants ship with the theme: .info, .warning, and .box. Each is plain <div> markup. An optional <strong> first child renders as the callout heading.
- [Tables](/tables.md): Plain <table> markup. The theme styles every table the same way: a thin rule above and below the table, a divider under the header row, and tight vertical rhythm sized down half a step from body text. No striping or grid lines — columns should read by alignment, not borders.
- [Lists and definitions](/lists.md): Unordered, ordered, and definition lists all render with the same vertical rhythm as body paragraphs. Definition lists carry extra responsibility in this theme — they’re the standard shape for option references and they switch to a hanging-indent layout in wide containers.
- [Variables](/variables.md): Any token of the form $NAME$ in the source is replaced at build time with the value declared in options.variables. Substitution runs as the final pass over the fully rendered page, so the same syntax reaches content, embedded files, and shell fragments like the logo and footer.

## API reference style

- [API reference style](/api-reference.md): Two pieces of markup turn an ordinary article into an API reference page: <section class="api"> for methods, endpoints, or components, and <dt class="api"> for the options under them. Both render with a monospace heading and both feed the client-side symbol search index.

## Reference

- [Configuration](/configuration.md): 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:
- [Navigation](/navigation.md): The left-hand nav and the prev/next links at the bottom of every page are both driven by a single JSON manifest. Group articles into chapters or list them flat, point the plugin at the file, and the nav, headings, and inter-page links fall out automatically.
- [Search](/search.md): The theme ships with two complementary search indexes: Pagefind for prose (full-text search across the site) and a fuzzysort-backed index for API symbols (instant lookup by name). Both are static — they live in files written next to the built site — so the deployed app has no backend to host.
- [Themes](/themes.md): The theme ships with light and dark palettes built on the light-dark() CSS function. A visitor’s preference is persisted in localStorage and applied before paint so the page never flashes the wrong palette during load.
- [Pipeline extensions](/pipeline.md): The HTML pipeline is a sequence of cheerio passes — small async functions that receive a parsed document and mutate it in place. Two extension points let consumer projects splice their own passes in: transformers run before the built-in passes, finalizers run after. Both receive the same shape, so deciding which to use is mostly a question of ordering.
- [Deployment](/deployment.md): The built site is a folder of static files. There’s no server-side component, no runtime configuration, and no rebuild required to deploy to a new path. The relativize pass rewrites every internal URL to be page-relative, so _site/ works under any URL prefix.
- [Releases](/releases.md): Release notes for @carrotsearch/eleventy-apidocs — a short summary of what each version contributed. The dates come from the <time> element on each section; the theme fills in the readable form from its datetime attribute.