Add a Voice AI Agent to a MkDocs Site

AnveVoice

Add a Voice AI Agent to a MkDocs Site

Add the AnveVoice voice agent to a MkDocs or Material for MkDocs documentation site with a custom_dir template override, then rebuild and test.

How to add AnveVoice to a MkDocs documentation site

MkDocs builds plain HTML, so the tag goes into a theme template. Point theme.custom_dir at an override folder, add a main.html that extends base.html, and place the script in the scripts block. Rebuild and deploy, and the voice button appears on every docs page. Steps checked against the official documentation on 2026-10-14.

At a glance

Where the code goes: overrides/main.html (or custom_theme/main.html) in the scripts block, set through theme.custom_dir in mkdocs.yml
Coding needed: One YAML line and a short Jinja template; no plugin
Plan limits: None from MkDocs; it is open-source software you host yourself (GitHub Pages, Netlify, Cloudflare Pages and so on)
Time: About 5 minutes plus your normal build and deploy

How MkDocs decides what ends up in the page

MkDocs turns Markdown into static HTML by rendering each page through a theme. The theme owns the surrounding markup: header, navigation, footer and the script tags at the bottom. That matters here, because the AnveVoice tag is a script element, and raw HTML placed inside a Markdown file only appears on that single page. The MkDocs documentation on customizing your theme describes the supported route for site-wide additions: set custom_dir under theme in mkdocs.yml, and any file in that folder with the same name as a file in the parent theme replaces it. A file named main.html that extends base.html lets you override individual blocks instead of copying the whole theme. The same mechanism works for the popular Material for MkDocs theme, which documents an overrides folder with its own main.html. There is also an extra_javascript option in mkdocs.yml. The configuration reference describes it as a list of JavaScript files in your docs_dir that the theme includes as script tags, and it supports a mapping form with path and an optional async key. Because the documentation frames it around files in docs_dir and says nothing about external addresses, this guide uses the template override, which is the route the theme documentation spells out for loading a script from anywhere.

1. Get your install tag — Sign in at app.anvevoice.app, create the bot for your docs site and copy the embed ID. Replace YOUR_EMBED_ID below. Add &position=bottom-left or &theme=dark to the URL if you want to move the button or match a dark documentation theme. Code: <script src="https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID" async></script>

Method 1: override the scripts block with main.html

This works for the built-in mkdocs and readthedocs themes and for Material for MkDocs. The folder name is your choice; the examples use overrides. In the Material and base themes the scripts block is documented as the place for JavaScript that should run after the page content (it renders in the footer area). If you prefer the tag in the head, use the extrahead block instead; both accept the same tag.

1. Declare the override folder — Open mkdocs.yml and add custom_dir under theme. A relative path is resolved against the folder that contains mkdocs.yml. Code: theme: name: material custom_dir: overrides
2. Create overrides/main.html — Create the folder next to mkdocs.yml and add main.html. It must extend base.html. Calling super() keeps the theme's own scripts, which is important: a block that only contains your tag would replace the parent's block entirely. Code: {% extends "base.html" %} {% block scripts %} {{ super() }} <script src="https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID" async></script> {% endblock %}
3. Rebuild — Run mkdocs serve to preview, or mkdocs build to produce the site folder. Template overrides are read at build time, so restart the preview server if the page does not change.

Method 2: add it to one page only

If you want the voice agent on a single page, such as a getting-started guide, you can write the script element directly in that page's Markdown file. MkDocs passes raw HTML through. A site-wide template override is cleaner for the whole documentation set, but the inline route avoids touching the theme.

Deployment and caching notes for documentation sites

Remember that MkDocs output is static. Editing main.html changes nothing on your live site until you rebuild and redeploy (for example with mkdocs gh-deploy or your CI pipeline).
Instant navigation: Material for MkDocs can load pages without a full reload when navigation.instant is enabled. The AnveVoice script ignores a second copy on the page, so a repeated load is harmless, but test navigating between pages after enabling that feature.
Search-and-print: the voice button is a page overlay; it does not alter the generated search index or the printable output of your Markdown content.
HTTPS: browsers only allow the microphone on secure pages, so a docs site served from http:// will show the button but the microphone prompt will not appear. GitHub Pages and most static hosts provide HTTPS by default.

Check that it works

1. Inspect the built HTML — After mkdocs build, open any generated index.html in the site folder and search for embed.js. The tag should appear once, near the end of the body.
2. Open the deployed docs — Visit the live site in a private window, look for the round microphone button at the bottom-right, click it, allow the microphone and ask a question your docs answer.

Common problems

Navigation or search stops working after the override: main.html replaced a block without calling super(). Add {{ super() }} as the first line inside the block.
Nothing changes: custom_dir points at the wrong folder or main.html is not directly inside it. The path is relative to mkdocs.yml, not to docs/.
Tag appears in the wrong place: you used the head block while the rest of your scripts load in the footer. Either position works because the tag is asynchronous.
Button hidden behind a theme element: the theme's fixed footer or cookie banner may overlap bottom-right. Add &position=bottom-left to the tag URL.

Sources

MkDocs: Customizing Your Theme (custom_dir, main.html, blocks) (https://www.mkdocs.org/user-guide/customizing-your-theme/) — checked 2026-10-14
MkDocs: Configuration (extra_javascript, theme custom_dir) (https://www.mkdocs.org/user-guide/configuration/) — checked 2026-10-14
Material for MkDocs: Customization (overrides, scripts block) (https://squidfunk.github.io/mkdocs-material/customization/) — checked 2026-10-14

Try AnveVoice on your site

Free plan: $0, 50,000 tokens a month, no card. Get your embed ID in the dashboard, then paste one tag.