Type to search.

↵ to open ↑↓ to navigate Esc to close

Code blocks

Basics

Code blocks use the <pre data-language="..."> contract. Shiki provides dual-theme syntax highlighting. 

function greet(name) {
  return `Hello, ${name}!`;
}

const message = greet("apidocs");

HTTP requests

The http language highlights request and response examples — method line, headers, and body. 

POST /v1/users HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Bearer token

{
  "name": "apidocs"
}

Highlighting lines

Add a directive comment to mark lines for emphasis. highlight-line marks the comment's own line; highlight-next-line marks the line after; highlight-range{N-M} marks an arbitrary range. The directive line itself is stripped from the rendered code. 

function ping() {
  console.log("warming up");
  console.log("this line is highlighted");
  console.log("done");
}

Multi-line range:

const config = {
  host: "localhost",
  port: 8080,
  scheme: "https"
};

Hiding lines

hide-line, hide-next-line, and hide-range{N-M} drop lines from the rendered output — useful for omitting boilerplate while keeping the runnable source intact. 

export function publicApi() {
  return "visible in the docs";
}

Embedding files

Reference an external file with data-embed. The path is resolved relative to the source HTML. The language is inferred from the file extension unless overridden. 

// Example apidocs configuration — referenced from the docs via data-embed.

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

// fragment-start{minimal}
export default async function (eleventyConfig) {
  return apidocs(eleventyConfig, {
    contentDir: "src/content"
  });
}
// fragment-end{minimal}

// fragment-start{with-variables}
export async function withVariables(eleventyConfig) {
  return apidocs(eleventyConfig, {
    contentDir: "src/content",
    variables: {
      VERSION: "0.1.18",
      OWNER: "Carrot Search"
    }
  });
}
// fragment-end{with-variables}

Embedding a fragment

data-fragment extracts a labelled chunk delimited by fragment-start{id} and fragment-end{id} markers in the source file. 

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

Embedding via JSONPath

For structured data, data-jsonpath extracts matching nodes from a JSON file. Each match becomes its own block. 

{
  "summary": "List users",
  "parameters": [
    {
      "name": "limit",
      "in": "query",
      "schema": {
        "type": "integer"
      }
    }
  ]
}