Documentation Build

next.config.ts registers remark-gfm (GitHub-flavoured markdown) and my custom Remark (Markdown parsing and serialization) plugin, which allows:

• Defining subtitle and flag visibility within a YAML frontmatter block
• Using ::: fences for formatting content
• Using shortcodes: {.heart} () / {.lock} () / {.gear} () / {.select} (SELECT) / {.insert} (INSERT) / {.update} (UPDATE) / {.delete} (DELETE) / {.get} (GET) / {.post} (POST) / {.put} (PUT) / {.patch} (PATCH) / {.button} (button link) / {.blank} (target="_blank") / [text]{.smallcaps} (small caps)

The Remark plugin also pulls page metadata out of the paired content.mdx so page.tsx can import it:

• title — The # heading, which informs the browser tab
• toc — ## / ### headings, used for the sticky-note table of contents and anchor links
• frontmatter — The YAML defined at the top of the page

next.config.ts also registers Rehype (HTML parsing and serialization) plugins:

• rehype-slug adds id to each heading from its text so that anchor links are functional.
• My custom plugin runs rehype-highlight (our themed syntax highlighting) with a small language set we use in the docs.

Articles feature a sidebar inspired by the poetry book pages, and a sticky-note table of contents, courtesy of DocsPage.

loadDatabaseOpenApi.ts:

• Caches the fetch (React cache() plus a 60-second revalidate) so the API Library sidebar and the Scalar API explorer share one request on /docs/api. Guides do not fetch OpenAPI.
• After fetch it stamps our info title/description, apikey / bearerAuth security, and servers overlay.
• Overlays required PostgREST row filters on PATCH / DELETE (replacing the matching $ref) so Test Request does not list the same query parameter twice.
• typesToOpenApi.ts still builds sidebar links from Scalar inline call anchors (openApiNav) and marks non-anon operations as requiring a JWT.

DocsApiReferenceView:

• Loads the @scalar/api-reference browser bundle from /docs/api/scalar-standalone and renders it after the content in src/app/docs/api/content.mdx, which also displays differently depending on the build.
• page.tsx preloads that script so the download overlaps the article render, and streams a Loading API reference skeleton behind Suspense until the spec is ready. On the public build, the view waits until the stored project ref is read from sessionStorage before mounting Scalar.
• Enables the Enter Your Supabase Project ID field above the explorer, pointing test requests at the visitor's entered project on the public build.

For every documentation page except API Library (/docs/api), Search Docs opens the shared overlay powered by DocsSearch.tsx:

• DocsSearchProvider loads /docs/search-index the first time Search Docs or the landing search bar opens (not on /docs/api, which uses Scalar search). Until the index arrives the overlay shows Indexing….
• searchTerms.ts expands light English inflections at index and query time (managing ↔ manage), with prefix match and a bit of fuzzy room on longer terms.

What Gets Indexed

• Host pages only (**/content.mdx); _snippets are never rendered or indexed independently
• Snippet imports are inlined into the host before flattening headings/body
• When FLAG_PUBLIC=true, pages with public: false are omitted (anything under "Internal" in the sidebar)
• {.public} / {.private} fences and *-public embed pairs resolve through the live Remark plugin so public deploys never index private-only copy
• OpenAPI / Scalar operations are not returned in the user guide search — only other docs .mdx files (including /docs/api prose from api/content.mdx when it is searchable)