Add a Voice AI Agent to a VitePress Site (2026)

How to add AnveVoice to a VitePress site

VitePress has a head option in its site config that takes a list of tags. Add the AnveVoice script there, with async set, and rebuild. The tag is written into every page's HTML, and you can also add it to single pages through front matter. Steps checked against the official documentation on 2026-10-14.

At a glance

• Where the code goes: The head array in .vitepress/config.ts (or .js / .mts)
• Coding needed: A few lines in the config file
• Plan limits: None from VitePress. Free AnveVoice plan is enough
• Time: About 2 minutes plus a build

The head option

VitePress's site-config reference defines head as an array of tags, each written as a tuple: the tag name, an attributes object, and optionally the inner content. Its own example for an external script is a tuple with the script tag name and an object holding async and src. That is the pattern to follow for AnveVoice. The getting-started guide explains that the .vitepress directory is a reserved location for the config file, and that it may be JavaScript or TypeScript depending on how the setup wizard created it. Your content folder, often docs, sits beside it; the .vitepress folder is inside that folder in a typical project.

• 1. Get your embed ID — Create a bot at app.anvevoice.app, copy the embed ID, and use it in place of YOUR_EMBED_ID. You can add &position=bottom-left or &theme=dark. Code: <script src="https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID" async></script>

Method 1: sitewide, in the site config

• 1. Open .vitepress/config.ts — Use config.js or config.mts if that is what your project has. Keep your title, description, themeConfig and other settings.
• 2. Add a head entry — Inside defineConfig, add the array. If a head array already exists, add a new line to it. Code: import { defineConfig } from 'vitepress' export default defineConfig({ // ...title, description, themeConfig head: [ ['script', { async: '', src: 'https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID' }] ] })
• 3. Run or build — npm run docs:dev starts the dev server. npm run docs:build writes the static site to .vitepress/dist, the default output the guide names.

Method 2: a single page or a section

The frontmatter reference lists a head option that adds extra tags for the current page, merged with the site-level ones. Use it when only a pricing or support page needs the voice agent. Put this at the top of that Markdown file. Because VitePress navigates between pages without reloading the document, a tag that exists on only one page may stay loaded after the visitor moves to another page. Treat a per-page tag as sitewide in practice, or verify the behaviour in your build.

• 1. Add front matter — Each tag is a nested YAML list: the name, then its attributes. Code: --- head: - - script - async: '' src: https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID ---

How merging works, and transformHead

The reference says head entries from site config, locale config, directory config, front matter and the transformHead hook are merged in that order, and that a later entry replaces an earlier one with the same key instead of being appended. If you give your tag an id attribute, the same key in a locale or page can override it. Without conflicts, nothing is replaced. transformHead is a build hook for tags that cannot be written statically, for example a script that depends on the page. The docs state it runs only during a build, not during dev, and its tags are not updated during client-side navigation. For AnveVoice's fixed URL, the static head array is the better fit.

VitePress-specific gotchas

• VitePress prerenders pages to HTML and then hydrates them as a single-page app. The head array is baked into the HTML for every page at build time.
• Dev server and build both honour the static head array, so you will see the voice button while writing docs. Gate it with a build-time check if you do not want that.
• The docs site currently shows 2.0 alpha in its version menu with 1.x as the earlier release. The head option is documented on the current reference page; if you are on 1.x, check that page for your version.
• Node.js 22 or later is required by the current getting-started guide.
• Put the .vitepress/dist output behind HTTPS. Browsers block microphone access on plain HTTP.

Check that it works

• 1. Build — Run npm run docs:build, then npm run docs:preview if your project defines it, or open the dist folder from any static server.
• 2. Inspect the HTML — Open .vitepress/dist/index.html and search for anvevoice.app in the head.
• 3. Use it on a live page — In a private window, load the deployed site, click the round microphone button at bottom-right and allow the microphone.

Common problems

• head has no effect: you put it inside themeConfig. It is a top-level key of the site config.
• async has no effect: confirm the attributes object is the second element of the tuple, as in the example, and that the page source shows async on the script.
• Per-page tag duplicates: the same script is in both the config and a page. Remove one.
• Old content after deploying: purge the CDN or host cache and hard reload.

Sources

• VitePress docs: site config (head, transformHead) (https://vitepress.dev/reference/site-config) — checked 2026-10-14
• VitePress docs: frontmatter config (head) (https://vitepress.dev/reference/frontmatter-config) — checked 2026-10-14
• VitePress docs: getting started (config location, build output) (https://vitepress.dev/guide/getting-started) — checked 2026-10-14

Related

• How to add AnveVoice to a Docusaurus site
• How to add AnveVoice to a MkDocs documentation site
• How to add AnveVoice to a Hugo site
• How to add AnveVoice to a plain HTML website

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.