Connect: Astro

Connect an Astro site. Astro must render the blog on the server, so it needs output: "server" and an adapter for your host.

This is the simple way: we send finished HTML with the SEO done, and your site shows it in its own design. Using a coding agent? Copy the prompt from your dashboard's Integration page instead: it has your values filled in and the same steps for this framework.

How it works

• The key comes from the environment. BLOGSFORSEO_API_KEY is read on the server and sent as Authorization: Bearer <key>. It's never in the code, the templates or the browser.
• Every visit asks our API. The pages are rendered on each request, never saved at build time, so new posts, edits and removals show up on their own. The one rule for caching: nothing may keep our API's answer for more than 5 minutes. If you add a cache, keep it at 300 seconds or less, and check your CDN rules on /blog and /blog-sitemap.xml too.
• A 404 from us is a 404 from you. An unknown or removed post must answer a real 404, not an empty page. Any other error fails the request, so your framework shows its normal error page.

Match the routes to your post URL pattern in the dashboard: these use /blog and /blog/{slug}. In this guide, {API} means https://blogsforseo.com/api/v1.

Set it up

Astro 7 with the Node adapter (any server adapter works the same way). The key is an Astro secret, read when the server runs, never bundled.

// astro.config.mjs
import node from "@astrojs/node";
import { defineConfig, envField } from "astro/config";

export default defineConfig({
  output: "server", // Every page renders on each request, so new posts appear by themselves.
  adapter: node({ mode: "standalone" }),
  env: {
    schema: {
      BLOGSFORSEO_API_KEY: envField.string({ context: "server", access: "secret" }),
      BLOGSFORSEO_API_URL: envField.string({ context: "server", access: "public", default: "https://blogsforseo.com" }),
    },
  },
});

// src/lib/blogsforseo.ts
import { BLOGSFORSEO_API_URL, getSecret } from "astro:env/server";

const API = BLOGSFORSEO_API_URL.replace(/\/$/, "") + "/api/v1";
export const SLUG = /^[a-z0-9-]+$/;

/** Asks the Content API on every request. Returns null on a 404; any other error throws (a 500 page). */
export async function bfs(path: string, query: Record<string, string | number> = {}): Promise<Response | null> {
  const key = getSecret("BLOGSFORSEO_API_KEY");
  if (!key) throw new Error("BLOGSFORSEO_API_KEY is not set");
  const url = new URL(API + path);
  for (const [name, value] of Object.entries(query)) url.searchParams.set(name, String(value));
  const response = await fetch(url, { headers: { Authorization: `Bearer ${key}` }, signal: AbortSignal.timeout(10_000) });
  if (response.status === 404) return null;
  if (!response.ok) throw new Error(`Blogs for SEO API answered ${response.status} for ${path}`);
  return response;
}

/** ?page= as a whole number from 1; anything else is page 1. */
export function pageNumber(url: URL): number {
  const page = url.searchParams.get("page") ?? "";
  return /^[1-9]\d{0,5}$/.test(page) ? Number(page) : 1;
}

---
// src/pages/blog/index.astro
import Layout from "../../layouts/Layout.astro";
import { bfs, pageNumber } from "../../lib/blogsforseo";

const response = await bfs("/html/posts", { page: pageNumber(Astro.url) });
if (!response) return new Response("Not found", { status: 404 });
const { body } = await response.json();
---
<Layout title="Blog">
  <Fragment set:html={body} />
</Layout>

---
// src/pages/blog/[slug].astro: unknown slug shapes are a 404 without asking the API.
import Layout from "../../layouts/Layout.astro";
import { bfs, SLUG } from "../../lib/blogsforseo";

const slug = Astro.params.slug ?? "";
const response = SLUG.test(slug) ? await bfs("/html/posts/" + slug) : null;
if (!response) return new Response("Not found", { status: 404 });
const { head, body } = await response.json();
---
<Layout>
  <Fragment slot="head" set:html={head} />
  <Fragment set:html={body} />
</Layout>

Your layout needs <slot name="head" /> inside <head>, and no <title> of its own on post pages.

// src/pages/blog-sitemap.xml.ts (src/pages/llms.txt.ts is the same with "/llms.txt" and text/plain)
import type { APIRoute } from "astro";
import { bfs } from "../lib/blogsforseo";

export const GET: APIRoute = async () => {
  const response = await bfs("/sitemap", { format: "xml" });
  return new Response(response ? await response.text() : "", { status: response ? 200 : 404, headers: { "Content-Type": "application/xml" } });
};

• IndexNow key file: save public/<your IndexNow key>.txt containing just the key.
• robots.txt: add the sitemap line from your dashboard (Sitemap: https://<your domain>/blog-sitemap.xml) to public/robots.txt.
• Run it: astro build, then node dist/server/entry.mjs with BLOGSFORSEO_API_KEY set in the server's environment.

The advanced way

Fetch /posts and /posts/{slug} instead of the /html endpoints, and build the page from the fields in the Content API reference, following the advanced guide. bodyHtml is already sanitised: print it raw. When you put jsonLd in a <script type="application/ld+json">, escape <:

JSON.stringify(post.jsonLd).replace(/</g, "\\u003c")

Check it

Run these against your site (local or live). -A GPTBot asks the way an AI crawler does, without JavaScript:

curl -A GPTBot https://<your domain>/blog                 # lists posts, or "No posts yet"
curl -A GPTBot https://<your domain>/blog/<a post slug>   # <h1>, article text, canonical link, application/ld+json
curl -i https://<your domain>/blog/not-a-real-post        # HTTP 404
curl https://<your domain>/blog-sitemap.xml               # the same posts as GET {API}/sitemap
curl https://<your domain>/llms.txt                       # plain text
curl https://<your domain>/<your IndexNow key>.txt        # just the key
curl https://<your domain>/robots.txt                     # has the Sitemap: line

Then check it stays fresh: the number of posts on /blog matches total from the API. Finish with the simple guide's dashboard steps: check the post address, run the health check and connect Search Console.