Smarter Chat for Documentation Sites

A documentation site is where a product’s users ask questions, and a Smarter LLMClient with the docs in a vectorstore can answer them on the page. One setting adds its chat button to every page of a site built with Docusaurus, MkDocs (with any theme, including Material for MkDocs), Sphinx (with any html theme, including Read the Docs’ and Furo) or VitePress. The chat renders in its own Shadow DOM, so the site’s theme can’t break it, and it survives the client-side navigation of Docusaurus, Material and VitePress.

Each integration writes the tag of the embed script of @smarter.sh/ui-chat, with the same options, and fails the site’s build if the chatbot’s url is missing or invalid. Their source is github.com/smarter-sh/smarter-docs-site-generators. In every case, first allow the site’s origin (e.g. https://<project>.readthedocs.io) in the LLMClient’s spec.config.prompt.allowedOrigins, and apply its manifest.

Docusaurus

npm install @smarter.sh/docusaurus-plugin-smarter-chat

// docusaurus.config.js
export default {
  plugins: [["@smarter.sh/docusaurus-plugin-smarter-chat", { chatbot: "https://docs-bot.example.com/" }]],
};

MkDocs and Material for MkDocs

pip install mkdocs-smarter-chat

# mkdocs.yml
plugins:
  - search
  - smarter-chat:
      chatbot: https://docs-bot.example.com/

Sphinx

pip install sphinx-smarter-chat

# conf.py
extensions = ["sphinx_smarter_chat"]
smarter_chat_chatbot = "https://docs-bot.example.com/"

On Read the Docs, add sphinx-smarter-chat to the docs’ requirements file. Every option is a config value prefixed smarter_chat_.

VitePress

VitePress needs no package: one head entry in .vitepress/config.mts.

export default defineConfig({
  head: [["script", {
    src: "https://cdn.jsdelivr.net/npm/@smarter.sh/ui-chat@0.9.0/dist/embed.js",
    "data-chatbot": "https://docs-bot.example.com/",
    async: "",
  }]],
});

Options

The same options in every integration, named in its own style (apiKey in JavaScript, api_key in YAML and Python, data-api-key in VitePress’s tag):

Option	Default	Description
`chatbot`	(required)	The deployed LLMClient’s url.
`apiKey`		Only for an LLMClient that has api keys. It is public in the pages.
`position`	`bottom-right`	`bottom-right` or `bottom-left`.
`label`, `color`	`Chat`, `#ff5733`	The button’s accessible name and color.
`open`	`false`	Start open.
`height`, `width`	`600px`, `400px`	The panel’s size.
`version`	the integration’s	The version of `@smarter.sh/ui-chat` to load from jsDelivr, or a range, e.g. `0.9`.
`src`		The url or path of a self-hosted `embed.js`, with its `embed/` directory beside it.

Other Generators

Any other generator (Hugo, Jekyll, Astro, Eleventy) takes the embed script’s tag in its base template, before </body>:

<script src="https://cdn.jsdelivr.net/npm/@smarter.sh/ui-chat@0/dist/embed.js"
  data-chatbot="https://docs-bot.example.com/" async></script>