OneTag AI / Guides

Add AI to an Astro site

How do I add AI features to an Astro site without server endpoints?

Astro builds to static HTML, which is why it is fast and why it cannot keep a secret: an OpenAI key in a component ends up in the browser bundle. You could add a server endpoint and switch to SSR, but then you need a host that runs it, a key in an environment variable and a rate limiter so the endpoint is not abused.

OneTag AI keeps the site static. A public key with a token budget goes in the page, and onetag.ask is the only API. This guide adds a "ask this page" box to an Astro layout.

Steps

1. Get a free key

   From onetagai.com, by email.

2. Add the tag to your layout

   In src/layouts/Layout.astro, inside <head>. Astro leaves plain script tags alone, so use is:inline to keep it out of the bundler:

   <script is:inline src="https://onetagai.com/v1.js" data-key="YOUR_ONETAG_KEY"></script>

3. Make a component

   src/components/AskPage.astro:

   <form id="ask">
     <input name="q" placeholder="Ask this page" required>
     <button>Ask</button>
   </form>
   <p id="answer"></p>
   
   <script>
     const form = document.getElementById("ask");
     const out = document.getElementById("answer");
     form.addEventListener("submit", async (e) => {
       e.preventDefault();
       out.textContent = "";
       await onetag.ask(new FormData(form).get("q"), document.querySelector("main"), {
         stream: (delta) => { out.textContent += delta; },
       });
     });
   </script>

4. Use it

   Drop <AskPage /> into any page or layout. Astro bundles the component script; onetag is already defined by the inline tag, so there is nothing to import.

Where the key lives

The key is public, so it can sit in the layout as a string. If you prefer, put it in PUBLIC_ONETAG_KEY in .env and render it with import.meta.env.PUBLIC_ONETAG_KEY; Astro inlines PUBLIC_ variables at build time. Either way it ends up in the HTML, which is the design.

Content collections and blogs

For a blog, pass the article element instead of main so the model sees only the post. A TL;DR button on every post is three lines; the summarize button guide has the complete pattern, and a talking mascot for Astro blog themes is on the templates page.

Starlight docs

On a Starlight documentation site, the useful feature is "ask the docs": a question answered from the relevant pages, not just the current one. That needs a small build-time index because one call takes up to 32,000 characters. The ask-the-docs guide explains the approach; the astro-onetag integration packages it.

TypeScript

Declare the global once in src/env.d.ts:

declare const onetag: {
  ask(prompt: string, input?: unknown, options?: Record<string, unknown>): Promise<string>;
};

Questions

Related guides

• Add 'ask the docs' AI search to a documentation site
• Add a TL;DR summary button to blog posts
• Add AI to a GitHub Pages site
• Ways to add AI to a static site, compared

Updated 2026-11-09. Something wrong or missing? Email support@odysseyx.app.