Docs plugin

htmx-ui-plugin-docs turns the pages under /docs into documentation: every section linkable, every page also published as Markdown, and indexes for search engines, site search and AI agents. One navigation file drives the sidebar, previous/next links and the order of everything it publishes. This website's docs are built with it; see AI agents for what the output looks like.

Install#

bun add htmx-ui-plugin-docs

npm install htmx-ui-plugin-docs

pnpm add htmx-ui-plugin-docs

yarn add htmx-ui-plugin-docs

import { defineConfig } from "htmx-ui-engine";
import docs from "htmx-ui-plugin-docs";

export default defineConfig({
  url: "https://example.com", // absolute URLs in the sitemaps; $SITE_URL overrides it
  plugins: [docs({ name: "Acme", description: "Acme's docs." })],
});

@import "tailwindcss";
@import "htmx-ui/styles.css";
@import "htmx-ui-plugin-docs/styles.css";

import { initMarkdownCopy } from "htmx-ui-plugin-docs/client";

document.addEventListener("DOMContentLoaded", () => initMarkdownCopy());

The docs layout#

The plugin reads pages the way they are rendered, so it needs three things from your docs layout: an <article> whose first h1 is the page title, the page body inside <div data-docs-content>, and a <meta name="description">. An .eyebrow in the article names the page's section.

{% extends "layouts/base.html" %}
{% from "docs/macros.html" import markdown_actions %}
{% set nav = docsNav(url) %}

{% block content %}
  <aside>
    {% for group in nav.sections %}
      <p>{{ group.title }}</p>
      {% for item in group.items %}
        <a href="{{ item.href }}"{% if item.href == nav.active %} aria-current="page"{% endif %}>{{ item.title }}</a>
      {% endfor %}
    {% endfor %}
  </aside>
  <article>
    <p class="eyebrow">{{ nav.section }}</p>
    <h1>{{ title }}</h1>
    {{ markdown_actions(url) }}
    <div data-docs-content class="prose">{% block docs %}{% endblock %}</div>
    {% if nav.prev %}<a href="{{ nav.prev.href }}">{{ nav.prev.title }}</a>{% endif %}
    {% if nav.next %}<a href="{{ nav.next.href }}">{{ nav.next.title }}</a>{% endif %}
  </article>
{% endblock %}

Navigation#

One file lists the docs in order, in sections. It is found through the template roots, like json():

{
  "sections": [
    {
      "title": "Getting started",
      "items": [
        { "title": "Introduction", "href": "/docs" },
        { "title": "Installation", "href": "/docs/installation", "description": "Set it up." }
      ]
    }
  ]
}

docsNav(url) returns where a page sits in it:

Entries can carry anything else you need (this site marks components with "component": true to list them on the components page). Pages missing from the file still get Markdown, and sort with their closest listed parent.

Heading anchors#

Every h2 and h3 in [data-docs-content] gets an id from its text and a # link, styled by htmx-ui's .heading-anchor. An explicit id is kept, so give one to a heading whose wording may change while links to it must not. Headings inside links, .not-prose component markup, .demo previews and [data-md-skip] are not sections and are left alone. The HTML, the Markdown and the sitemap all see the same ids.

What it publishes#

htmx-ui dev and the server adapters generate them on request; htmx-ui build writes them to dist/. Mark purely visual blocks data-md-skip to leave them out of the Markdown and the search text.

Macros#

{% from "docs/macros.html" import demo, classes, markdown_actions %}

{% call demo() %}<button class="btn btn-primary">Save</button>{% endcall %}
{{ classes([["btn", "The base class."], ["btn-primary", "The main action."]]) }}
{{ markdown_actions(url) }}

Options#

For other plugins#

Its api renders and converts pages for plugins that build on it:

const docs = config.plugins.find((p) => p.name === "docs")?.api as DocsApi | undefined;
for (const page of docs?.pages() ?? []) console.log(page.url, page.title, page.sections.length);

pages() renders every page (with title, description, section, headings and sections), markdown(page) converts one, and isDocs(url) tells docs pages from the rest. The converters and generators are exported too: pageMarkdown, pageMeta, addHeadingAnchors, sitemapJson, llmsTxt.