RootSmith Docs

Static sites

Publish to a Next.js static export, Astro, Hugo, Jekyll, Eleventy, or another static site with a deploy hook. RootSmith starts a new build of your site each time you publish.

Use this when your host serves only files, such as a Next.js site with output: "export", or a static site generator such as Astro, Hugo, Jekyll, or Eleventy. A static site has no refresh handler, so RootSmith starts a build instead. A publish takes as long as one build.

In Publishing, choose how your site is built, then select Set up SDK for a Next.js static export or Show setup steps for another static site. The steps have your site's values and a prompt for your coding agent.

1. Read pages when your site builds

Next.js

Follow the Next.js SDK guide with two changes:

  • Leave out app/api/rootsmith/route.ts and ROOTSMITH_CONNECTION_SECRET.
  • Return every page from generateStaticParams:
app/[...path]/page.tsx
export async function generateStaticParams() {
  const pages = await rootSmith.listAllPages()
  if (!pages.length) return [{ path: ["rootsmith-placeholder"] }]
  return pages.map((page) => ({ path: page.path.slice(1).split("/") }))
}

Next.js rejects an empty list under output: "export". The placeholder path keeps the build working before your first page publishes. It renders as a 404.

Set ROOTSMITH_SITE_ID in your host's build environment.

Astro, Eleventy, and other JavaScript builds

Install @rootsmithio/client and call listAllPages() at build time. Render each page body with renderHtml(page), which includes the version marker. For example, in Astro:

src/pages/[...path].astro
---
import { createRootSmith, renderHtml } from "@rootsmithio/client"

export async function getStaticPaths() {
  const rootSmith = createRootSmith({
    siteId: import.meta.env.ROOTSMITH_SITE_ID,
  })
  const pages = await rootSmith.listAllPages()
  return pages.map((page) => ({
    params: { path: page.path.slice(1) },
    props: { page },
  }))
}

const { page } = Astro.props
---

<h1>{page.title}</h1>
<Fragment set:html={renderHtml(page)} />

Hugo, Jekyll, and other builds

Read the public JSON API at build time. It needs no key and returns only published pages:

curl "https://api.rootsmith.io/v1/delivery/$ROOTSMITH_SITE_ID/pages?page=1"

Each response has up to 25 pages, sorted by path. Request the next page number until a response has fewer than 25. To read only one page type, add prefix, such as prefix=/blog. The other options are in Pagination. Each page has id, revision, title, description, path, markdown, url, siteName, publishedAt, and updatedAt. Render the Markdown with your generator, and add the version marker to the page:

<div
  data-rootsmith-content="{id}"
  data-rootsmith-version="{revision}"
  hidden
></div>

For example, Hugo can read the API with resources.GetRemote, and a Jekyll plugin or a script that runs before the build can write the pages to your content folder.

Serve each page at its path without a trailing slash, such as /blog/ai-search-guide. The live check doesn't follow redirects, so a page that redirects to /blog/ai-search-guide/ must be confirmed by hand.

To split a blog index into numbered pages at build time, see Pagination.

2. Create a deploy hook

Create a deploy hook in your host, such as Vercel, Netlify, or Cloudflare Pages. It must be a public HTTPS URL. A key in the query string, as Render uses, is fine.

3. Save it in RootSmith

In Publishing, under How is your site built?, choose Next.js static export or Static or Markdown site, paste the hook URL, and select Save.

RootSmith never shows a saved hook URL again. To change it, paste a new one. An agent sets this with update_publishing_settings, using fallbackDelivery: "build" and the URL in webhookUrl.

What happens when you publish

  1. RootSmith makes the new version public in its API.
  2. It sends an empty POST to your deploy hook.
  3. Your build reads the new version.
  4. RootSmith checks the live page every five minutes for 24 hours and marks it published when it finds the version marker.

If the hook fails, the previous version stays public.

Merged pages

A static site can't send a redirect for a merged page. Add the redirects in your host's configuration, then confirm them in RootSmith. Retiring the old pages starts a build that removes them.

On this page