Set up blog pages with the SDK

This is the source of truth for integrating a RankBuddy-powered blog into a Next.js App Router app. AI coding agents should follow every required section below and substitute project-specific values from the user’s prompt (BLOG_PATH, SITE_URL, PROJECT_NAME).

SDK on npm

@rankbuddy/sdk — headless client, ISR helpers, React HTML renderer.

Article fields

Full reference for RankBuddyArticle and RankBuddyCluster.

What you are building

Routes

{BLOG_PATH} — article index (listing + topic strip)
{BLOG_PATH}/[slug] — article detail (HTML for humans and search)
{BLOG_PATH}/[slug].md — markdown twin for AI agents (via rewrite + Route Handler)
{BLOG_PATH}/topic/[clusterSlug] — topic hub (recommended)
{BLOG_PATH}/layout.tsx — passthrough layout for cache invalidation

Data

Server Components fetch published content via @rankbuddy/sdk ISR helpers (not raw fetch to RankBuddy).

SEO

Per-page generateMetadata using article seo.* fields, JSON-LD BlogPosting, and robots when seo.noIndex.

Styling

Clean Tailwind layout: readable prose for HTML body, card grid on index, clay accent #D97757, responsive and accessible.

Replace {BLOG_PATH} with the user’s path (e.g. /blog). Replace {SITE_URL} with their production origin (e.g. https://acme.com).

1. Install dependencies

npm install @rankbuddy/sdk@^0.3.5

Requires Next.js ≥ 14.2 and Node 18+. React is optional unless you use @rankbuddy/sdk/react.

2. Environment variables

Add to .env.local and your hosting provider:

RANKBUDDY_API_KEY=rn_live_...

Server-only. Never prefix with NEXT_PUBLIC_. Never import the client in Client Components with a secret key.

3. SDK client (server)

Create src/lib/rankbuddy.ts:

import { createRankBuddyClient } from "@rankbuddy/sdk";

function getRankBuddyApiKey() {
  const apiKey = process.env.RANKBUDDY_API_KEY;
  if (!apiKey) {
    throw new Error("RANKBUDDY_API_KEY is required to render RankBuddy blog pages.");
  }
  return apiKey;
}

const siteUrl = process.env.NEXT_PUBLIC_SITE_URL ?? "https://example.com";
const blogPath = process.env.RANKBUDDY_BLOG_PATH ?? "/blog";

export const rankBuddy = createRankBuddyClient({
  apiKey: getRankBuddyApiKey(),
  siteUrl,
  blogPath,
});

Set NEXT_PUBLIC_SITE_URL and RANKBUDDY_BLOG_PATH to match the user’s project, or hardcode values from the onboarding prompt.

4. Route map (App Router)

For {BLOG_PATH} = /blog:

src/app/blog/
  layout.tsx
  page.tsx
  [slug]/page.tsx
  topic/[clusterSlug]/page.tsx

Use a route group if needed (src/app/(marketing)/blog/...) — URLs stay /blog/....

Blog layout

src/app/blog/layout.tsx:

export const dynamic = "force-static";
export const revalidate = false;

export default function BlogLayout({ children }: { children: React.ReactNode }) {
  return children;
}

Keep the blog layout static in production. This prevents parent layouts from turning public blog pages into private, no-store responses and lets Vercel or the Next.js Full Route Cache serve cached HTML instantly.

5. Use SDK ISR helpers (required)

On Next.js, do not call rankBuddy.articles.getBySlug directly in Server Components. Use cached helpers so revalidateTag works:

Page	SDK helper	Cache tag
Index	`getArticlesList`, `getClustersList`	`blogListingCacheTag()`
Article	`getArticleBySlug`	`blogArticleCacheTag(slug)`
Topic hub	`getClusterBySlug`, `getClusterArticles`	`blogTopicListingCacheTag(clusterSlug)`
Related block	`getRelatedArticles`	`blogRelatedCacheTag(slug)` + `blogRelatedAllCacheTag()`
`generateStaticParams`	`getArticlesList`, `getClusterSlugs`	listing tag

import {
  getArticleBySlug,
  getArticlesList,
  getClustersList,
  getClusterArticles,
  getClusterBySlug,
  getRelatedArticles,
  getClusterSlugs,
} from "@rankbuddy/sdk";
import { rankBuddy } from "@/lib/rankbuddy";

const post = await getArticleBySlug(rankBuddy, slug);
const posts = await getArticlesList(rankBuddy, { limit: 24 });

See article fields for every property to render.

6. Blog index (`{BLOG_PATH}/page.tsx`)

Required behavior:

export const dynamic = "force-static" for public blog HTML.
export const revalidate = 3600 for first launch (see Caching); use false only with a revalidation strategy.
Fetch getArticlesList(rankBuddy, { limit: 24 }) and getClustersList(rankBuddy) in parallel.
Render an empty state when there are no posts.
Each card shows: coverImage, title, excerpt || description, publishedAt, readingTime, link to {BLOG_PATH}/{slug}.
Topic strip links to {BLOG_PATH}/topic/{cluster.slug}.
Static generateMetadata for the index (title, description, canonical, Open Graph).

Minimal styling: max-width container, responsive grid or stacked cards, subtle borders, hover states, sufficient color contrast.

7. Article page (`{BLOG_PATH}/[slug]/page.tsx`)

Required behavior:

export const dynamic = "force-static" and export const dynamicParams = true.
generateStaticParams — paginate getArticlesList (e.g. limit: 100) to prebuild slugs; wrap in try/catch so missing API key at build time does not fail CI.
generateMetadata — map from article fields:

export async function generateMetadata({ params }): Promise<Metadata> {
  const { slug } = await params;
  const post = await getArticleBySlug(rankBuddy, slug);
  if (!post) return {};

  const title = post.seo?.title ?? post.title;
  const description = post.seo?.description ?? post.description;
  const image = post.seo?.ogImage ?? post.coverImage;
  const canonical = post.seo?.canonicalUrl ?? `${siteUrl}${blogPath}/${post.slug}`;

  return {
    title,
    description,
    keywords: post.seo?.keywords,
    alternates: { canonical },
    openGraph: {
      title,
      description,
      type: "article",
      url: canonical,
      images: image ? [{ url: image }] : undefined,
      publishedTime: post.publishedAt,
      modifiedTime: post.updatedAt,
    },
    twitter: {
      card: "summary_large_image",
      title,
      description,
      images: image ? [image] : undefined,
    },
    robots: post.seo?.noIndex ? { index: false, follow: false } : undefined,
  };
}

Alternatively: await rankBuddy.seo.generateMetadata(slug) returns a Next-compatible metadata object. Page UI must include:

Element	Source
`<h1>`	`post.title`
Cover hero	`post.coverImage`
Byline	`publishedAt`, `readingTime`
Topic link	`post.primaryCluster` → topic page
Tags	`post.tags` or `post.seo.keywords`
Body	`post.content.html` (see below)
Related posts	cluster articles or `getRelatedArticles(rankBuddy, slug)`
Back link	to `{BLOG_PATH}`

Article body — choose one:

// Option A (recommended): sanitized React helper
import { RenderContent } from "@rankbuddy/sdk/react";
<RenderContent content={post.content} />

// Option B: Tailwind Typography prose + trusted server HTML
<div
  className="prose prose-slate max-w-none dark:prose-invert"
  dangerouslySetInnerHTML={{ __html: post.content.html }}
/>

Hide duplicate <h1> in HTML if the page already renders post.title (e.g. [&>h1:first-child]:hidden). JSON-LD (recommended): BlogPosting + BreadcrumbList scripts with headline, description, image, datePublished, dateModified, url. Call notFound() when getArticleBySlug returns null.

8. Markdown endpoints (AI) — required

Serve raw markdown at {BLOG_PATH}/[slug].md so AI agents get clean source without HTML chrome. Reuse the same getArticleBySlug data cache — no separate cache tag or invalidation logic.

Rewrite (`next.config.ts`)

Add a rewrite (adjust {BLOG_PATH} if not /blog):

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  async rewrites() {
    return [
      {
        source: "/blog/:slug.md",
        destination: "/api/rankbuddy/markdown/:slug",
      },
    ];
  },
};

export default nextConfig;

Replace /blog with the user’s {BLOG_PATH} (no trailing slash).

Shared helpers

Create src/lib/blog/articleMarkdown.ts. Centralizing canonical-URL logic here (instead of duplicating it in the HTML page and the Route Handler) guarantees alternates.canonical on the HTML page and Link: rel="canonical" on the .md response always agree:

import type { RankBuddyArticle } from "@rankbuddy/sdk";

const SITE_URL = process.env.NEXT_PUBLIC_SITE_URL ?? "https://example.com";
const BLOG_PATH = process.env.RANKBUDDY_BLOG_PATH ?? "/blog";

// `@rankbuddy/sdk` types `content.source` as the raw markdown field; some API
// versions return `content.markdown` instead. Support both.
type ArticleMarkdownContent = RankBuddyArticle["content"] & { markdown?: string };

function resolveMarkdownSource(content: RankBuddyArticle["content"]): string {
  const { markdown, source } = content as ArticleMarkdownContent;
  return markdown ?? source ?? "";
}

export function toAbsoluteUrl(value?: string | null, base: string = SITE_URL): string {
  if (!value) return base;
  try {
    return new URL(value, base).toString();
  } catch {
    return base;
  }
}

export function getArticleCanonicalUrl(post: RankBuddyArticle): string {
  return toAbsoluteUrl(post.seo?.canonicalUrl ?? `${BLOG_PATH}/${post.slug}`);
}

export function getArticleMarkdownUrl(canonicalUrl: string): string {
  return `${canonicalUrl.replace(/\/+$/, "")}.md`;
}

function toYamlString(value: string): string {
  // A double-quoted JSON string is a valid YAML flow scalar — safely escapes
  // quotes/colons/newlines without a YAML dependency.
  return JSON.stringify(value);
}

function buildFrontmatter(post: RankBuddyArticle, canonicalUrl: string): string {
  const lines = [
    "---",
    `title: ${toYamlString(post.title)}`,
    `description: ${toYamlString(post.description)}`,
    `url: ${toYamlString(canonicalUrl)}`,
    post.publishedAt ? `published: ${toYamlString(post.publishedAt)}` : null,
    post.updatedAt ? `updated: ${toYamlString(post.updatedAt)}` : null,
    "---",
  ].filter((line): line is string => line !== null);

  return lines.join("\n");
}

export function buildArticleMarkdownDocument(post: RankBuddyArticle, canonicalUrl: string): string {
  const frontmatter = buildFrontmatter(post, canonicalUrl);
  const body = resolveMarkdownSource(post.content).trim();
  return `${frontmatter}\n\n${body}\n`;
}

export function buildArticleMarkdownHeaders(canonicalUrl: string): HeadersInit {
  return {
    "Content-Type": "text/markdown; charset=utf-8",
    // Prevents Google/Bing from indexing this as a duplicate of the HTML page.
    "X-Robots-Tag": "noindex, nofollow",
    // Some clients would otherwise trigger a file download instead of reading the body.
    "X-Content-Type-Options": "nosniff",
    Link: `<${canonicalUrl}>; rel="canonical"`,
    // The data layer is already cached (and invalidated) via `blogArticleCacheTag`.
    // Don't let a CDN cache the HTTP response separately — it has no invalidation
    // hook and would go stale after a publish/update.
    "Cache-Control": "no-store",
  };
}

Route Handler

Create src/app/api/rankbuddy/markdown/[slug]/route.ts:

import { getArticleBySlug } from "@rankbuddy/sdk";
import { NextResponse } from "next/server";

import {
  buildArticleMarkdownDocument,
  buildArticleMarkdownHeaders,
  getArticleCanonicalUrl,
} from "@/lib/blog/articleMarkdown";
import { rankBuddy } from "@/lib/rankbuddy";

// `unstable_cache` (used inside `getArticleBySlug`) requires the Node.js runtime.
export const runtime = "nodejs";
// Rewritten per-request from `/blog/:slug.md`; never statically prerendered.
export const dynamic = "force-dynamic";

type RouteContext = { params: Promise<{ slug: string }> };

function notFound() {
  return new NextResponse("Not Found", { status: 404, headers: { "Cache-Control": "no-store" } });
}

export async function GET(_req: Request, ctx: RouteContext) {
  const { slug } = await ctx.params;

  let decodedSlug: string;
  try {
    decodedSlug = decodeURIComponent(slug);
  } catch {
    return notFound();
  }

  try {
    const post = await getArticleBySlug(rankBuddy, decodedSlug);
    if (!post) {
      return notFound();
    }

    const canonicalUrl = getArticleCanonicalUrl(post);
    const body = buildArticleMarkdownDocument(post, canonicalUrl);

    return new NextResponse(body, {
      status: 200,
      headers: buildArticleMarkdownHeaders(canonicalUrl),
    });
  } catch (error) {
    console.error("[GET /api/rankbuddy/markdown/:slug]", error);
    return new NextResponse("Internal Server Error", {
      status: 500,
      headers: { "Cache-Control": "no-store" },
    });
  }
}

Always wrap the SDK call in try/catch: an unhandled throw would fall back to Next.js’s default HTML error page, breaking the text/markdown contract for bots.

HTML discovery (`generateMetadata`)

On the article page, reuse the same helpers so the canonical URL can never drift between representations:

import { getArticleCanonicalUrl, getArticleMarkdownUrl } from "@/lib/blog/articleMarkdown";

const canonical = getArticleCanonicalUrl(post);

// inside the returned Metadata object:
alternates: {
  canonical,
  types: {
    "text/markdown": getArticleMarkdownUrl(canonical),
  },
},

SEO rules (required)

Set X-Robots-Tag: noindex, nofollow on every .md response — prevents duplicate indexing; AI crawlers can still fetch the URL.
Do not add .md URLs to sitemap.xml.
Do not link to .md URLs in the UI — only the <link rel="alternate"> in metadata.
Serve the same content as HTML (from content.markdown / API source); do not maintain a separate AI-only text.
Don’t add Vary: Accept on the .md response — that header is only meaningful when the same URL negotiates representations by Accept. Here .md is a distinct URL, so it doesn’t apply.

Caching

The Route Handler calls getArticleBySlug — same blogArticleCacheTag(slug) as the HTML page. Existing revalidateTag(blogArticleCacheTag(slug)) after publish updates both representations. No changes to your revalidation helper are required. Keep the HTTP response itself no-store (see helper above) so a CDN can’t serve a stale copy past a publish.

9. Topic hub (`{BLOG_PATH}/topic/[clusterSlug]/page.tsx`)

Required behavior:

export const dynamic = "force-static" and export const dynamicParams = true.
generateStaticParams from getClusterSlugs(rankBuddy).
getClusterBySlug(rankBuddy, clusterSlug) — notFound() if null.
getClusterArticles(rankBuddy, clusterSlug, { limit: 24 }) for the grid.
Metadata from cluster.name, cluster.notes, cluster.pillarKeyword, cluster.keywords.
Same card component as the index.

10. Caching

First launch (recommended)

export const revalidate = 3600; // refresh at most once per hour

Published articles appear on your site within the revalidation window without extra infrastructure.

Production (on-demand)

export const dynamic = "force-static";
export const revalidate = false;

Use this on {BLOG_PATH}/layout.tsx, {BLOG_PATH}/page.tsx, {BLOG_PATH}/[slug]/page.tsx, and {BLOG_PATH}/topic/[clusterSlug]/page.tsx. For dynamic pages, keep dynamicParams = true so newly published slugs can be generated after deploy. Pair with revalidateTag + targeted revalidatePath calls after publishes. Tags from @rankbuddy/sdk:

blogArticleCacheTag(slug)
blogListingCacheTag()
blogRelatedAllCacheTag()
blogRelatedCacheTag(slug)
blogTopicListingCacheTag(clusterSlug)

import { revalidatePath, revalidateTag } from "next/cache";
import {
  blogArticleCacheTag,
  blogListingCacheTag,
  blogRelatedAllCacheTag,
  blogRelatedCacheTag,
  blogTopicListingCacheTag,
} from "@rankbuddy/sdk";

revalidateTag(blogArticleCacheTag(slug));
revalidateTag(blogListingCacheTag());
revalidateTag(blogRelatedCacheTag(slug));
for (const clusterSlug of clusterSlugs) {
  revalidateTag(blogTopicListingCacheTag(clusterSlug));
  revalidatePath(`/blog/topic/${clusterSlug}`);
}

revalidatePath("/blog");
revalidatePath(`/blog/${slug}`);
if (previousSlug && previousSlug !== slug) {
  revalidateTag(blogArticleCacheTag(previousSlug));
  revalidateTag(blogRelatedCacheTag(previousSlug));
  revalidatePath(`/blog/${previousSlug}`);
}

// Use for publish, unpublish, slug changes, or sitemap-visible changes.
revalidateTag(blogRelatedAllCacheTag());
revalidatePath("/sitemap.xml");

Do not use revalidatePath("{BLOG_PATH}", "layout") for routine article updates. It invalidates the whole blog subtree, so the next visitors and crawlers pay the full regeneration cost across many pages. Revalidate the exact index, article, topic, and sitemap paths instead.

Verify caching after deploy

Run two requests against the same article:

curl -I https://example.com/blog/my-article
curl -I https://example.com/blog/my-article

The HTML response should not include Cache-Control: private, no-store. On Vercel, repeat requests should show x-vercel-cache: HIT or a similarly cached response. If every request is MISS with private, no-store, a layout or route is still dynamic.

11. Base styling spec

Agents should ship production-ready pages without a design system dependency:

Font: system sans or project default
Accent: use the primary brand color from the onboarding prompt (Primary brand color: #RRGGBB). If none was detected from the site, RankBuddy defaults to #0F172A (Tailwind slate-900)
Index: card layout with 16:9 cover thumbnails, title, 2-line excerpt
Article: max-width ~48rem prose column, optional sidebar
Dark mode: support if the host app uses dark: classes
Images: alt from title, lazy loading, object-cover on cards
Accessibility: semantic <article>, <time dateTime>, focus states on links

12. Agent checklist

Before finishing, verify:

All three routes exist under the user’s {BLOG_PATH}.

RANKBUDDY_API_KEY is read only on the server.

SDK ISR helpers used instead of raw client list/get calls.

Every RankBuddyArticle SEO field in article fields is mapped in generateMetadata.

seo.noIndex sets robots correctly.

generateStaticParams tolerates missing API key at build time.

Empty index state explains that posts come from RankBuddy after publish.

Markdown .md endpoint at {BLOG_PATH}/[slug].md with noindex and alternates.types['text/markdown'] on the HTML page.

Production blog HTML is static/SSG and repeat requests are cache hits, not private, no-store dynamic responses.

User can follow Publish your first article after deploy.

Next step

Deploy, then publish from RankBuddy — see Publish your first article.

Get started

Integrations

SDK reference

Set up blog pages with the SDK

SDK on npm

Article fields

What you are building

1. Install dependencies

2. Environment variables

3. SDK client (server)

4. Route map (App Router)

Blog layout

5. Use SDK ISR helpers (required)

6. Blog index (`{BLOG_PATH}/page.tsx`)

7. Article page (`{BLOG_PATH}/[slug]/page.tsx`)

8. Markdown endpoints (AI) — required

Rewrite (`next.config.ts`)

Shared helpers

Route Handler

HTML discovery (`generateMetadata`)

SEO rules (required)

Caching

9. Topic hub (`{BLOG_PATH}/topic/[clusterSlug]/page.tsx`)

10. Caching

First launch (recommended)

Production (on-demand)

Verify caching after deploy

11. Base styling spec

12. Agent checklist

Next step

SDK on npm

Article fields

​What you are building

​1. Install dependencies

​2. Environment variables

​3. SDK client (server)

​4. Route map (App Router)

​Blog layout

​5. Use SDK ISR helpers (required)

​6. Blog index ({BLOG_PATH}/page.tsx)

​7. Article page ({BLOG_PATH}/[slug]/page.tsx)

​8. Markdown endpoints (AI) — required

​Rewrite (next.config.ts)

​Shared helpers

​Route Handler

​HTML discovery (generateMetadata)

​SEO rules (required)

​Caching

​9. Topic hub ({BLOG_PATH}/topic/[clusterSlug]/page.tsx)

​10. Caching

​First launch (recommended)

​Production (on-demand)

​Verify caching after deploy

​11. Base styling spec

​12. Agent checklist

​Next step

What you are building

1. Install dependencies

2. Environment variables

3. SDK client (server)

4. Route map (App Router)

Blog layout

5. Use SDK ISR helpers (required)

6. Blog index (`{BLOG_PATH}/page.tsx`)

7. Article page (`{BLOG_PATH}/[slug]/page.tsx`)

8. Markdown endpoints (AI) — required

Rewrite (`next.config.ts`)

Shared helpers

Route Handler

HTML discovery (`generateMetadata`)

SEO rules (required)

Caching

9. Topic hub (`{BLOG_PATH}/topic/[clusterSlug]/page.tsx`)

10. Caching

First launch (recommended)

Production (on-demand)

Verify caching after deploy

11. Base styling spec

12. Agent checklist

Next step