Add a Voice AI Agent to a Hexo Blog

How to add AnveVoice to a Hexo site

Hexo generates static HTML from your theme's templates. The most upgrade-proof way to add the AnveVoice tag is a small file in your site's scripts folder that calls Hexo's injector to place it before the closing body tag. Editing the theme layout also works. Steps checked against the official documentation on 2026-10-14.

At a glance

• Where the code goes: scripts/anvevoice.js in the site root (injector), or the theme's layout template
• Coding needed: A 6-line JavaScript file, or one pasted line in a template
• Plan limits: None from Hexo itself; you host the generated public folder yourself
• Time: About 5 minutes plus hexo generate and deploy

Why the injector beats editing the theme

A Hexo site is built from three layers: your Markdown posts, the site configuration, and a theme folder containing layout templates, theme scripts and static assets. Most people install a theme from npm or clone it into themes/. If you paste a script tag into that theme and later update it, your change is overwritten. Hexo provides an injector for exactly this. According to the Hexo API documentation, hexo.extend.injector.register takes an entry (where in the HTML to insert), a value (a string or a function that returns one) and an optional target that limits which layouts receive it. The entry values include head_begin, head_end, body_begin and body_end. Hexo also loads any JavaScript file you put in the site's scripts folder during initialization, as the plugins documentation explains, so a one-file script is all you need and no theme is modified. One caution from the documentation: its own sample for a script tag omits the closing script element. When you register a tag, include the closing tag yourself.

• 1. Get your install tag — From app.anvevoice.app, copy the embed ID of the bot you created for this site and substitute it for YOUR_EMBED_ID. Optional URL parameters are &position=bottom-left and &theme=dark. Code: <script src="https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID" async></script>

Method 1: register the tag with the injector (recommended)

To limit the voice agent to part of the site, pass a third argument. The injector accepts default, home, post, page, archive, category, tag or a custom layout name, for example register('body_end', tag, 'post') for article pages only.

• 1. Create the scripts folder — In the root of your Hexo project (the folder that holds _config.yml, source and themes), create a folder named scripts if it does not exist yet.
• 2. Add scripts/anvevoice.js — Create the file with the following content. Single quotes wrap the string so the double quotes in the tag need no escaping. body_end places the tag right before the closing body tag of every generated page. Code: hexo.extend.injector.register( 'body_end', '<script src="https://anvevoice.app/embed.js?embedId=YOUR_EMBED_ID" async></script>' );
• 3. Clean and regenerate — Run hexo clean to delete the cache file db.json and the public folder, then hexo generate to rebuild. Preview with hexo server, which listens on port 4000 by default.

Method 2: paste the tag into the theme layout

Hexo's template documentation explains that layouts hold the structure shared across templates, and that every layout must contain a body variable where the page content is placed. The theme documentation lists the theme folder as _config.yml, languages, layout, scripts and source. Inside layout, find the shared layout file (its extension depends on the template engine your theme uses: .ejs, .njk and so on) and paste the tag just before the closing body tag. Work on a fork or a copy of the theme, since an update to the original theme will remove your edit.

• 1. Locate the layout file — Open themes/<your-theme>/layout and find the file that wraps every page, usually named layout.ejs, layout.njk or similar.
• 2. Paste the tag — Place the AnveVoice script line directly above the closing body tag, save, then run hexo clean and hexo generate.

Deploying and cache considerations

• hexo generate writes static files into public. The voice button only appears on the live site after you run your normal deploy (hexo deploy, a CI job or a host that builds from Git).
• If the site sits in a subdirectory, set url and root correctly in _config.yml; this does not affect the AnveVoice tag, which uses an absolute address, but it affects how your own pages are served.
• CDN and browser caches may hold older HTML. Purge the cache of your host or CDN after the first deploy that includes the tag.
• The tag must be served over HTTPS for the microphone to work; use HTTPS on the hosting side.

Check that it works

• 1. Search the generated output — After hexo generate, search the public folder for embed.js. It should appear in each page you targeted, once per page.
• 2. Test the live page — Open the deployed blog in a private window. The round microphone button appears bottom-right; click it, allow microphone access and ask a question about your posts.

Common problems

• No button after deploy: the generated files were stale. Run hexo clean first, then hexo generate, and confirm the tag is in public/index.html.
• The injector file does nothing: it is in the theme's scripts folder of a theme you later replaced, or the file is not in the site-level scripts folder. Keep it at the project root.
• Broken page after editing the layout: a closing tag was removed while pasting. Compare against the original template.
• Button appears on every page when you wanted posts only: pass the third argument to register to target a layout.

Sources

• Hexo API: Injector (https://hexo.io/api/injector) — checked 2026-10-14
• Hexo Docs: Plugins (scripts folder) (https://hexo.io/docs/plugins) — checked 2026-10-14
• Hexo Docs: Templates (layouts) (https://hexo.io/docs/templates) — checked 2026-10-14
• Hexo Docs: Themes (https://hexo.io/docs/themes) — checked 2026-10-14
• Hexo Docs: Commands (clean, generate, server) (https://hexo.io/docs/commands) — checked 2026-10-14

Related

• How to add AnveVoice to a MkDocs documentation site
• How to add AnveVoice to a Jekyll site
• How to add AnveVoice to a Hugo site
• How to add AnveVoice to an Eleventy site

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.