Search and Comments

Search and comments are both site-level integrations: fill in a set of credentials in the site config, the build layer writes them into the page payload, and the theme chrome and islands mount the corresponding components on the client. Markdown content plays no part.

Algolia DocSearch

algolia: {
  appId: 'XXX',
  apiKey: 'XXX',       // search-only key, safe to expose
  indexName: 'xxx',
}

When configured, the navbar mounts a DocSearch box (the credentials ship with the payload; a search-only key is public by design). Three steps to wire it up:

1. Apply at DocSearch or create an index yourself in the Algolia console to get the three credentials; when the application review asks to verify site ownership, add the verification meta Algolia gives you through the head config (see configuration)
2. Fill them into the algolia field of the site config
3. Run one full re-crawl: the CSS selectors in the crawler config must match the new theme's DOM structure (content container, heading levels); selectors from an old site do not adapt automatically

The search box styling already follows light/dark; the style entry is src/client/theme/docsearch.css.

Giscus comments

giscus builds on GitHub Discussions and is the framework's built-in comment option. After picking a repo and category in the giscus.app wizard, fill the four generated values into the config:

giscus: {
  repo: 'owner/repo',           // public repo
  repoId: 'R_xxx',              // generated by the wizard
  category: 'General',          // Discussions category name
  categoryId: 'DIC_xxx',        // generated by the wizard
}

Behavior notes:

• When configured, the comment island is mounted automatically at the end of article pages — no manual tag in markdown; non-article pages like home and archives get none
• The comment iframe's light/dark theme follows site theme switches via postMessage: flipping the theme neither reloads the iframe nor loses comment state
• When comments coexist with the related-articles graph, the graph sits above the comment section
• The repo must meet giscus's prerequisites: public, Discussions enabled, giscus App installed

Selection advice

• A docs site (this site's shape) usually configures search only: DocSearch indexes documentation structure well, and it is free for open-source projects
• A blog should configure search and comments together; both credential sets are public values, so shipping them in the output is not a security concern
• Configure neither and the corresponding code is not bundled at all: the DocSearch and Giscus scripts load on demand only when configured; an unconfigured site pays zero bytes for them

This site has both configured: the search box in the navbar and the comment section at the bottom of any article are live — try them. The credentials are the two value sets in this repo's vite.config.ts.