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.tsandROOTSMITH_CONNECTION_SECRET. - Return every page from
generateStaticParams:
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:
---
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
- RootSmith makes the new version public in its API.
- It sends an empty
POSTto your deploy hook. - Your build reads the new version.
- 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.
Other JavaScript frameworks
Use @rootsmithio/client to show RootSmith pages in Astro, SvelteKit, Nuxt, or any JavaScript server, and refresh them the moment you publish.
Pagination
Split a blog or another index page into numbered pages. Works with the Next.js SDK, the client package, static builds, and the JSON API.