For MkDocs & Material for MkDocs

Ask AI for your MkDocs site

Q: Does it understand our Python API reference?

Yes. mkdocstrings-generated API references — function signatures, parameters, docstring bodies — are read as documentation. Citations resolve to the right function and anchor.

Q: Does it support versioned docs?

Yes. Each version mike publishes is indexed separately, and the chatbot scopes answers to the version the reader is on. A reader on /1.x/ does not get answers from /2.x/.

Q: What about translations and i18n?

Each language under mkdocs-static-i18n is indexed as its own source. Citations resolve to the right localized URL. Readers can also ask in 60+ languages even if your docs only ship in English.

Q: How long does the install take?

A small Jinja override at docs/overrides/main.html and one line in mkdocs.yml. Most teams are live in 15 minutes including indexing.

Drop in an Ask AI chatbot or AI search widget. Source-cited answers, multilingual out of the box, and a Content Gaps view that shows what your docs don't cover. Works on the default theme and Material for MkDocs. Live in 15 minutes.

Start free trial See the install code

14-day freeSelf-serveLive in 15 min

docs.acme.dev/api/rate-limits

Acme Docs

HomeGuidesAPI

Search/

Per-route rate limiting

Acme rate-limits requests per route. Each endpoint has its own bucket, configured at deploy time. Limits are enforced at the edge before requests reach your handler.

# Configure rate limit per route
curl -X PATCH https://api.acme.dev/v1/routes/checkout \
  -H "Authorization: Bearer sk_..." \
  -d '{"rate_limit": {"requests": 100, "per": "minute"}}'

Limits apply per project token. Authenticated traffic is metered separately from anonymous traffic, and burst windows can be tuned…

Used by teams that take their documentation seriously

Install

Three ways to ship Biel on MkDocs

A floating Ask AI chatbot, an AI search input you can drop in the navbar, or a hosted MCP endpoint Claude and Cursor can query directly. Same indexed content underneath.

Full installation guide

Add the chatbot via a custom_dir override

The documented MkDocs install. Create docs/overrides/main.html, drop the widget into a Jinja block, and point mkdocs.yml at it. Works on the default theme and Material for MkDocs.

→Floating Ask AI button on every page
→Five button positions, dark or light
→Modal docks bottom-right or floats
→Coexists with Material's built-in search

docs/overrides/main.html

<!-- 1. Add to mkdocs.yml: -->
<!--   theme:                  -->
<!--     custom_dir: overrides -->

{% extends "base.html" %}

{% block extrahead %}
<link rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.css">
<script type="module"
  src="https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.esm.js">
</script>
{% endblock %}

{% block content %}
{{ super() }}
<biel-button
  project="<YOUR_PROJECT_ID>"
  header-title="Documentation AI"
  button-position="bottom-right"
  modal-position="bottom-right"
  button-style="dark">
    Ask AI
</biel-button>
{% endblock %}

Use the search widget instead of the chat button

Same template override, swap the component. <biel-search-button> renders an AI search input you can place in a navbar block. Useful when readers should land on a search field rather than a floating button.

→Drop-in AI search field for the navbar
→Returns synthesized answer, not a list
→Can run alongside Material's search
→Same Jinja block, different element

docs/overrides/main.html

{% extends "base.html" %}

{% block extrahead %}
<link rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.css">
<script type="module"
  src="https://cdn.jsdelivr.net/npm/biel-search/dist/biel-search/biel-search.esm.js">
</script>
{% endblock %}

{% block header %}
{{ super() }}
<biel-search-button
  project="<YOUR_PROJECT_ID>"
  header-title="Documentation AI"
  button-style="rounded">
    Search
</biel-search-button>
{% endblock %}

Make your docs queryable by AI agents

Every Biel project ships with a hosted MCP endpoint. Claude, Cursor, Cline, and other MCP-compatible assistants can search your MkDocs site directly. Configure once in mcp.json or your editor’s MCP settings.

→Hosted MCP server, no self-hosting
→Same index as the chatbot, one source of truth
→Works with Claude Desktop, Cursor, Cline, Zed
→Auth via project token, scoped per-workspace

mcp.json

{
  "mcpServers": {
    "biel-ai": {
      "name": "Biel.ai",
      "type": "http",
      "url": "https://mcp.biel.ai/v2/YOUR_PROJECT_SLUG/mcp"
    }
  }
}

Biel.ai vs built-in MkDocs search

Honest read. The built-in lunr search is fast, free, and ships with MkDocs. Biel is built for natural-language questions with synthesized, source-cited answers. Many MkDocs sites run both.

Dimension	MkDocs search	Biel.ai
Query type	Lunr-based keyword and prefix matching, run client-side.	Natural-language questions. Returns a synthesized answer with source links.
Source attribution	A list of pages and headings where the keyword appears.	Direct answer plus a link to the specific page and section it came from.
mkdocstrings handling	Indexes function names and headings. Docstring bodies appear as raw text.	Reads docstring bodies as documentation. Cites specific functions and parameters.
Versioning (mike)	Each version has its own search; no cross-version awareness.	Per-version indexes. Scope answers to the user's current version automatically.
Material keyboard shortcuts	f, s, /, p, n shortcuts hijack input fields globally; can fight third-party widgets.	Ships with a 5-line shim that releases keystrokes when the chat is focused.
Analytics	Material exposes a query log via plugins; default theme has none. No content-gap signal.	Unanswered questions, satisfaction trends, and a Content Gaps view that updates daily.
Languages	Lunr language packs cover ~14 languages with stemming.	Answers in 60+ languages, including languages your docs are not written in.
Install	Built into MkDocs. No install required.	Template override at docs/overrides/main.html. Live in 15 minutes.
Cost	Free, included with MkDocs and Material.	From $50/mo, self-serve. 14-day free trial, no credit card required.

Things teams ask during evaluation

Will it work with Material for MkDocs?

Yes. Both the default MkDocs theme and Material for MkDocs are supported. Material adds a couple of keyboard shortcuts that we handle for you in the install guide.

Does it understand our Python API reference?

Yes. mkdocstrings-generated API references — function signatures, parameters, docstring bodies — are read as documentation. Citations resolve to the right function and anchor.

Does it support versioned docs?

Yes. Each version mike publishes is indexed separately, and the chatbot scopes answers to the version the reader is on. A reader on /1.x/ does not get answers from /2.x/.

Can we keep MkDocs' built-in search?

Yes. Many teams keep the built-in search for fast keyword lookup and use Biel.ai for natural-language questions. The two live in the same theme without conflict.

What about translations and i18n?

Each language under mkdocs-static-i18n is indexed as its own source. Citations resolve to the right localized URL. Readers can also ask in 60+ languages even if your docs only ship in English.

How long does the install take?

A small Jinja override at docs/overrides/main.html and one line in mkdocs.yml. Most teams are live in 15 minutes including indexing.

Where does our content go?

EU-hosted by default. GDPR compliant. Your content is never used to train models.

Make your MkDocs site answer questions

Start free trial Book a demo

14-day free trial · No credit card required · From $50/mo

Use a different platform? See our integration pages for Docusaurus, Sphinx, Starlight, Antora, and Jekyll.