Site Configuration (site.json)

apps/site/site.json is a manually maintained JSON file that controls global site metadata, RSS feeds, and time-sensitive UI elements (banners and badges).

It is imported via apps/site/next.json.mjs and exposed as a read-only API endpoint at /site.json.

This endpoint is also consumed externally by the doc-kit to display dynamic banners inside the API docs, for example security announcements or EOL notices, without requiring a doc-kit release.

Structure

Top-level metadata

Field	Description
title	Site title used in <title> and OG tags
description	Default meta description
favicon	Path to the favicon (relative to /public)
accentColor	Primary accent color (hex)

twitter

Social card metadata for Twitter/X.

Field	Description
username	Twitter handle (e.g. @nodejs)
card	Card type (summary, summary_large_image, etc.)
img	Path to the card image
imgAlt	Alt text for the card image

rssFeeds

Array of RSS feed definitions. Each feed is statically generated at /:locale/feed/:file.

Field	Description
title	Human-readable feed title
file	Output filename (e.g. blog.xml)
category	Blog category to include (all, release, vulnerability, …)

Adding a new feed here automatically makes it available; no code changes needed.

websiteBanners

A map of keys to banner definitions. Banners appear at the top of the target surface within the given date range.

Keys are either a page slug (for nodejs.org pages) or a major version string (for API doc pages). The doc-kit fetches this endpoint and matches banners by version key (e.g. "v24") or a special "all" key that applies to every API docs version.

"websiteBanners": {
  "index": {
    "startDate": "2026-01-13T00:00:00.000Z",
    "endDate":   "2026-01-20T00:00:00.000Z",
    "text": "January Security Release is available",
    "link": "https://nodejs.org/en/blog/vulnerability/…",
    "type": "warning"
  },
  "all": {
    "startDate": "2026-01-13T00:00:00.000Z",
    "endDate":   "2026-01-20T00:00:00.000Z",
    "text": "January Security Release affects all active versions",
    "link": "https://nodejs.org/en/blog/vulnerability/…",
    "type": "warning"
  },
  "v20": {
    "startDate": "2026-04-30T00:00:00.000Z",
    "endDate":   "2027-04-30T00:00:00.000Z",
    "text": "Node.js 20 is End-of-Life",
    "link": "https://nodejs.org/en/about/previous-releases",
    "type": "error"
  }
}

Field	Description
key	Page slug (e.g. index), major version (e.g. v20), or all for all API doc versions
startDate / endDate	ISO 8601 timestamps; the banner is hidden outside this range
text	Banner message
link	URL the banner links to
type	Visual style: warning (orange) or error (red)

websiteBadges

A map of page slugs to badge definitions. Badges appear as small promotional labels near the page title within the given date range.

"websiteBadges": {
  "index": {
    "startDate": "2025-10-30T00:00:00.000Z",
    "endDate":   "2025-11-15T00:00:00.000Z",
    "kind":  "default",
    "title": "Discover",
    "text":  "New migration guides",
    "link":  "https://nodejs.org/en/blog/migrations"
  }
}

Field	Description
key	Page slug
startDate / endDate	ISO 8601 timestamps; the badge is hidden outside this range
kind	Badge style variant (e.g. default)
title	Short label shown before the text
text	Badge body text
link	URL the badge links to

How to update

1. Edit apps/site/site.json directly. No code changes are required for banners, badges, or new RSS feeds.
2. Date-gated content (banners and badges) activates and deactivates automatically at runtime; no re-deploy is needed once the change is live.
3. After editing, run pnpm format to ensure the file remains consistently formatted.

API endpoint

The full contents of site.json are available at:

GET /site.json

The response is application/json and is statically cached at build time. It refreshes on each deployment.

External consumers

The doc-kit fetches this endpoint asynchronously on page load to inject banners into the Node.js API documentation site. This allows publishing announcements (security releases, EOL notices, etc.) that appear in the API docs without requiring a doc-kit release or a rebuild of the static documentation.