Originally published on dev.to. Cross-posted here for the Hashnode community.

Last week I had a problem.

I'd built an internal documentation site in Trilium Notes — about 30 notes covering product, marketing, and operations stuff. It was for non-technical teammates who needed to answer questions from developers about the platform.

The docs were good. Structured, searchable, complete. But reading 30 notes to find one answer is not great UX, especially for someone who's been pulled into a conversation and just needs the gist.

I wanted a chat bubble. The kind every modern docs site has. "Ask the docs anything."

So I built one. Single JS file, no build step, no dependencies. It drops into Trilium via a single relation and turns any share page into an AI-assisted docs site.

Here's the result, and how to add it to yours in 5 minutes.

What it does

• Floating "Ask the docs" chat bubble on every shared note page
• The AI uses tool calls search_notes(query) and read_note(noteId) to navigate your tree on demand
• Works with any OpenAI-compatible API: Gemini, OpenAI, OpenRouter, DeepSeek, Groq, local Ollama, vLLM…
• Each visitor enters their own API key (stored in their browser) no shared cost, no server-side secret
• Settings panel with live "Test connection" probe, fully editable system prompt
• Mounted inside Shadow DOM your docs CSS can't bleed in, ours can't bleed out

The whole thing is one widget.js file. ~740 lines. Plain ES2020+. No bundler.

How to install (5 steps)

You need TriliumNext ≥ 0.91 the version that supports the ~shareJs and ~shareCss relations.

1. Find your shared root note's ID

Right-click your shared root note in Trilium → Copy note ID, or grab it from the URL of your share page (e.g. https://your-trilium.com/share/<this-id>).

2. Create a code/JavaScript note

In Trilium: New note → type Code → MIME application/javascript. Paste the entire contents of widget.js.

3. Set your root note ID

Near the top of the file:

const ROOT_NOTE_ID = "REPLACE_ME_WITH_YOUR_ROOT_NOTE_ID";

Change to your actual root note ID from step 1.

4. Hide the JS note from the public sidebar

On the JS note, add label: #shareHiddenFromTree

5. Wire it up via ~shareJs

On your shared root note, add a relation:

• Name: shareJs
• Target: the JS note from step 2
• Inheritable: ✅ yes (this is critical, without it the script only loads on the root note, not on its descendants)

Hard-refresh the share page. A 💬 bubble appears in the bottom-right. First click pops the chat panel; first message prompts for an API key.

That's it.

How it works under the hood

Three things make this tick: the tool-use loop, TOC injection, and Shadow DOM.

The tool-use loop

Most "AI chat for docs" implementations either dump the full content into the prompt or run a vector-embedding pipeline. I went with neither, because Trilium gives me a clean tree structure I can let the model navigate itself.

The widget exposes two tools to the LLM:

const TOOLS = [
  {
    type: "function",
    function: {
      name: "search_notes",
      description: "Search for notes matching a query. Returns up to 8 best matches.",
      parameters: {
        type: "object",
        properties: { query: { type: "string" } },
        required: ["query"],
      },
    },
  },
  {
    type: "function",
    function: {
      name: "read_note",
      description: "Read the full text of a specific note by its noteId.",
      parameters: {
        type: "object",
        properties: { noteId: { type: "string" } },
        required: ["noteId"],
      },
    },
  },
];

The chat loop is straightforward keep calling the LLM until it stops asking for tools:

while (true) {
  const choice = await callLLM(history, base, key, model, systemPrompt, toc);
  history.push(choice.message);

  if (choice.finish_reason !== "tool_calls") break;

  for (const tc of choice.message.tool_calls) {
    const args = JSON.parse(tc.function.arguments);
    const result = (tc.function.name === "search_notes")
      ? searchNotes(args.query, idx)
      : readNote(args.noteId, idx);

    history.push({
      role: "tool",
      tool_call_id: tc.id,
      content: JSON.stringify(result),
    });
  }
}

searchNotes and readNote are pure JS they run against an in-memory cache of your notes (built once, on the first message). No extra HTTP calls per tool invocation.

TOC injection

The model needs to know what notes exist to know what to search for. Instead of describing the docs in prose ("This documentation covers product, marketing…"), I just dump a structural Table of Contents into the system prompt:

function buildToc(idx) {
  const lines = idx.map((n) =>
    `- \({n.title}  [\){n.noteId}]  (${n.breadcrumb})`
  );
  return "Table of contents:\n" + lines.join("\n");
}

So the LLM gets something like:

Table of contents:
- What is Visibility?  [S4qFGrSy9D5w]  (Knowledge Base › Product › What is Visibility?)
- Who Uses It  [Ovum6sM7fALz]  (Knowledge Base › Product › Who Uses It)
- The AI Agents Explained  [OePtXwrRuC7w]  (Knowledge Base › Product › The AI Agents Explained)
- ...

Now when a user asks "What does Visibility actually do?", the model sees What is Visibility? in the TOC and calls read_note("S4qFGrSy9D5w") directly no embedding lookup, no chunking. Just a model that can read.

This works because TOC is small (one line per note × ~30 notes ≈ 1.5 KB) and the model only fetches the bodies it actually needs. Token usage stays cheap even for hundreds of notes.

Shadow DOM isolation

Trilium's share page has its own CSS. CKEditor styles. Theme variables. Pre-existing rules for <button>, <input>, <label>, etc. If I render the widget directly into the page DOM, those styles bleed in and the form layout breaks in weird ways (I learned this the hard way).

Solution: Shadow DOM. The widget mounts into a closed-off shadow root:

const host = document.createElement("div");
host.id = "trilium-ai-host";
host.style.cssText = "all:initial;position:static";
document.body.appendChild(host);

const shadow = host.attachShadow({ mode: "open" });

const styleEl = document.createElement("style");
styleEl.textContent = css;
shadow.appendChild(styleEl);

// ...everything else gets appended to `shadow`, not `document.body`

Trilium's CSS can't reach inside the shadow root. My CSS can't reach outside. The two coexist without fighting.

CSS custom properties do pierce shadow boundaries (by inheritance), so my rules like background: var(--background-highlight, #2a2a2e) automatically pick up Trilium's theme light or dark, whatever the visitor chose.

What I'd do differently next time

A few things I learned that might save you time on similar projects:

1. Don't use innerHTML if you can avoid it. Trilium's note-content validator was rejecting my JS because it pattern-matched HTML-shaped strings inside template literals. Switching to createElementNS for SVG icons and document.createElement for everything else fixed it instantly.

2. The OpenAI tool-call format is the new lingua franca. I started with Anthropic's native API. Switched to OpenAI-compatible because it's what literally every provider speaks now: Gemini ships an OpenAI-compat shim, DeepSeek does, OpenRouter is built on it, every local LLM runtime exposes it. One format, every provider.

3. Per-visitor API keys are surprisingly OK for internal tools. I worried about asking each user to enter a key. In practice, the marketing team uses Gemini's free tier and never thinks about it again. No shared budget to manage, no key rotation, no server-side secrets to leak.

4. DeepSeek's reasoner needs reasoning_content echoed back. This one bit me, DeepSeek's reasoner model returns message.reasoning_content separately from message.content, and you have to include it in subsequent requests or you get a 400. Other providers don't care, but if you support DeepSeek, preserve it on the assistant message:

const entry = { role: "assistant", content: msg.content || "" };
if (msg.tool_calls?.length) entry.tool_calls = msg.tool_calls;
if (msg.reasoning_content) entry.reasoning_content = msg.reasoning_content;
history.push(entry);

Try it

Repo: github.com/mrbeandev/trilium-ai-agent

MIT licensed. Single file. No build step. PRs welcome.

If you've got a Trilium share, you can have AI on your docs in the time it takes to copy a JS file and add a relation. If you don't have a Trilium share but want one, TriliumNext is the most under-rated self-hosted note app in 2026 and it's worth the 10 minutes to set up.

Happy to answer questions in the comments.