Markdown table presentation, Consent, analytics, and auth-state hints, ts-seo plugin

Author: koculu

frontend/purestack.studio/guides/extending/plugins.mdx

@@ -91,18 +91,26 @@ The badge appears on the page. Change its `tone` in `plugins/site.ts` while the
 
 ## Standard plugins
 
-PureStack includes five plugins automatically in `build`, `serve`, and `publish`:
+PureStack includes nine plugins automatically in `build`, `serve`, and `publish`:
 
 | Package | Factory | Provides |
 | --- | --- | --- |
 | `@purestack/ts-components` | `componentsPlugin()` | Standard components, icons, and component styles |
-| `@purestack/ts-theme` | `themePlugin()` | The `doc` and `splash` templates, generated theme CSS, favicons, and theme switching |
-| `@purestack/ts-page-scripts` | `pageScriptsPlugin()` | Auth hint, consent and analytics, menus, navigation, code copying, search, TOC, Tabs, and Modal runtimes |
+| `@purestack/ts-theme` | `themePlugin()` | The `doc` and `splash` templates, generated theme CSS, favicons, theme switching, and Markdown table presentation |
+| `@purestack/ts-page-scripts` | `pageScriptsPlugin()` | Menus, navigation, code copying, search, TOC, Tabs, and Modal runtimes |
+| `@purestack/ts-page-scripts` | `authStateHintPlugin()` | Early signed-in state hint |
+| `@purestack/ts-page-scripts` | `consentPlugin()` | Consent browser runtime |
+| `@purestack/ts-page-scripts` | `analyticsPlugin()` | Direct or consent-managed GA4 integration |
+| `@purestack/ts-seo` | `seoPlugin()` | Social previews, canonical URLs, and translated alternate links |
 | `@purestack/ts-highlight` | `highlightPlugin()` | Shiki or highlight.js code highlighting |
 | `@purestack/ts-pagefind` | `pagefindPlugin()` | Full-build and lazy development search indexing |
 
 The stylesheet provider initializes before component factories, then all config hooks run in plugin order. Names do not affect initialization. Components belong to each build, so hooks can override them through `context.components`. The theme and page runtime plugins supply head templates that run before the selected page template, preserving its ability to inspect or change the completed head. The lifecycle hook set is unchanged.
 
+Metadata defaults compose through `headConfig({ site, pageInfo })` in plugin order, before explicit frontmatter `head` overrides and before head markup is rendered. It returns `BasicHeadConfig` or a promise. The SEO plugin uses this contribution for Open Graph, Twitter, canonical URLs, and translated alternate links; page templates receive the completed `headConfig`. Basic titles, descriptions, explicit head settings, and `index: false` enforcement remain in core.
+
+Auth hints, consent, and analytics are independent plugins in `ts-page-scripts`. The analytics plugin registers automatic GA4 consent services during `onConfigResolved`, before later config hooks and rendering. Omitting it removes automatic registration and direct tracking scripts. Explicitly configured consent services remain available. Analytics never bypasses enabled consent when the consent runtime plugin is omitted.
+
 To choose the standard integrations yourself, disable the automatic set and list the plugins you want. The factories are exported from `purestack`, `@purestack/ts-ssg`, and their individual packages:
 
 ```ts
@@ -114,7 +122,7 @@ export default defineConfig({
 })
 ```
 
-This keeps the layouts and components while omitting page runtimes, code highlighting, and search indexing. Theme switching and favicon generation belong to the theme plugin. Tabs and Modal scripts belong to the page scripts plugin, including automatic component embeds and explicit frontmatter settings. Without the theme plugin, another plugin must supply your page templates and any CSS output you need.
+This keeps the layouts and components while omitting automatic social metadata, page runtimes, code highlighting, and search indexing. Theme switching, favicon generation, and Markdown table wrappers belong to the theme plugin. Tabs and Modal scripts belong to the page scripts plugin, including automatic component embeds and explicit frontmatter settings. Without the theme plugin, another plugin must supply your page templates and any CSS output you need.
 
 An explicitly listed standard plugin replaces the automatic instance by name and keeps its initialization position. You can also use `createDefaultPlugins()` to obtain the complete set. In programmatic builds, use `options.defaultPlugins` alongside `options.plugins`.
 
@@ -210,6 +218,8 @@ Besides the prepared `head` and the page's `bodyHtml`, a template receives the p
 
 ## Transform Markdown
 
+Ordinary `rehypePlugins` run before `rehypePostPlugins`, which apply final presentation before outline collection and code highlighting. The theme plugin uses this final stage for `div.table-scroll`, so tables introduced by custom transforms receive the same scrolling behavior as source tables. Both stages run on pages and shared Markdown partials.
+
 `markdown` adds <a href="https://github.com/remarkjs/remark" target="_blank" rel="noopener">remark</a> plugins, which change the Markdown tree, and <a href="https://github.com/rehypejs/rehype" target="_blank" rel="noopener">rehype</a> plugins, which change the HTML tree. Every page, header, and footer goes through these steps:
 
 1. PureStack reads the Markdown. Regor markup, such as `<Badge tone="success">`, stays raw HTML.
@@ -534,8 +544,9 @@ Every field except `name` is optional.
 | `components` | `(config) => ({ [name]: component })` |
 | `templates` | Templates by name, each `(input) => TSNode<'html'>` |
 | `head` | `(input) => TSNode<'head'>`, or a promise; composes head markup before the page template |
+| `headConfig` | `({ site, pageInfo }) => BasicHeadConfig`, or a promise; metadata defaults before explicit page overrides |
 | `styles` | `(config) => SiteStyles`; one stylesheet provider, initialized before component factories |
-| `markdown` | `{ remarkPlugins?: PluggableList, rehypePlugins?: PluggableList }` |
+| `markdown` | `PureStackMarkdown`: remark, rehype, final rehype transforms, and highlighter providers |
 | `pages` | `({ config, files }) => { path, source }[]`, or a promise of them; `source` is the text, or a function that returns it |
 | `hooks` | Any of the hooks above |
 | `devMiddleware` | `(request, response) => void`, or a promise |

packages/ts-common/src/index.ts

@@ -39,6 +39,8 @@ export type {
   PageNavigationLinks,
 } from './navMenu-types'
 export type {
+  PageHeadConfigInput,
+  PageHeadConfigTemplate,
   PageHeadTemplate,
   PageInfo,
   PageTemplate,

packages/ts-common/src/page-template-types.ts

@@ -20,16 +20,24 @@ export interface PageTranslationInfo {
   relPath: string
 }
 
-export interface PageTemplateInput {
+export interface PageHeadConfigInput {
+  site: SiteConfig
+  pageInfo: PageInfo
+}
+
+/** Supplies head defaults before explicit page frontmatter overrides. */
+export type PageHeadConfigTemplate = (
+  input: PageHeadConfigInput,
+) => BasicHeadConfig | Promise<BasicHeadConfig>
+
+export interface PageTemplateInput extends PageHeadConfigInput {
   head: TSNode<'head'>
   bodyHtml: string
   headConfig?: BasicHeadConfig
   styleLinks?: ThemeStylesheetLink[]
   templateName: string
-  site: SiteConfig
   navigation?: PageNavigation
   outline?: PageOutlineItem[]
-  pageInfo: PageInfo
   headerHtml?: string
   footerHtml?: string
 }

packages/ts-page-scripts/README.md

@@ -16,11 +16,27 @@ also be imported from this package:
 import { pageScriptsPlugin } from '@purestack/ts-page-scripts'
 ```
 
-It preserves site configuration, page layout gates, consent-aware analytics,
+It preserves site configuration, page layout gates,
 and the site's base path. Theme startup belongs to `@purestack/ts-theme`;
 the plugin adds component-specific Tabs/Modal embeds through `onPageDocument`. Recorded component placement overrides frontmatter, and Tabs remains before Modal when both target the same parent.
 
 To omit the page runtimes, set `defaultPlugins: false` in `purestack.config.ts`
 or build options and list the other plugins you need.
 
+Three separate plugins from this package are also enabled by default:
+
+| Factory | Plugin name | Responsibility |
+| --- | --- | --- |
+| `authStateHintPlugin()` | `purestack:auth-state-hint` | Apply the signed-in hint before stylesheets load, when auth is enabled |
+| `consentPlugin()` | `purestack:consent` | Initialize the consent browser runtime when consent is enabled |
+| `analyticsPlugin()` | `purestack:analytics` | Add direct GA4 scripts without consent, or register the consent-managed GA4 service during `onConfigResolved` |
+
+Each factory can be selected independently of `pageScriptsPlugin()`. Omitting
+analytics removes automatic GA4 service registration as well as direct scripts;
+explicit user-defined consent services are preserved. When consent is enabled,
+analytics never bypasses it, including when the consent runtime plugin is omitted.
+The raw `resolveSiteConfig` result contains only explicitly configured consent
+services; automatic GA4 registration occurs when the analytics plugin initializes,
+before later config hooks and page rendering.
+
 For standalone `renderApp` calls, use `appendRuntimeScripts(document, runtimeEmbeds, frontmatter.embed)` from the renderer's `onRendered(document, runtimeEmbeds)` callback. The renderer itself has no knowledge of individual runtimes.

packages/ts-page-scripts/src/analyticsPlugin.ts

@@ -0,0 +1,70 @@
+import type {
+  ConsentCategory,
+  ConsentService,
+  Ga4Config,
+  PageTemplateInput,
+  SiteConfig,
+} from '@purestack/ts-common'
+import { h } from '@purestack/ts-html'
+import { buildGa4Script } from './buildGa4Script'
+
+/** Owns direct GA4 scripts and its optional consent-managed service. */
+export function analyticsPlugin() {
+  return {
+    name: 'purestack:analytics',
+    hooks: {
+      onConfigResolved({ config }: { config: SiteConfig }) {
+        if (config.consent.enabled)
+          config.consent.services = appendGa4ConsentService(
+            config.consent.services,
+            config.consent.categories,
+            config.analytics.ga4,
+          )
+      },
+    },
+    head({ head, site }: PageTemplateInput) {
+      const ga4 = site.analytics.ga4
+      if (ga4.enabled && ga4.measurementId && !site.consent.enabled) {
+        const payload = buildGa4Script(ga4)
+        head.push(
+          h('script').attr({ async: 'true', src: payload.src }),
+          h('script').raw(payload.init),
+        )
+      }
+      return head
+    },
+  }
+}
+
+function appendGa4ConsentService(
+  services: ConsentService[],
+  categories: ConsentCategory[],
+  ga4?: Ga4Config,
+) {
+  if (!ga4?.enabled || !ga4.measurementId) return services
+  const hasService = services.some((entry) => entry.id === ga4.serviceId)
+  if (hasService) return services
+  const hasCategory = categories.some(
+    (entry) => entry.id === ga4.consentCategory,
+  )
+  if (!hasCategory) {
+    throw new Error(
+      `analytics.ga4.consentCategory "${ga4.consentCategory}" does not exist in consent.categories.`,
+    )
+  }
+  return [
+    ...services,
+    {
+      id: ga4.serviceId,
+      category: ga4.consentCategory,
+      label: 'Google Analytics 4',
+      ga4MeasurementId: ga4.measurementId,
+      scripts: buildGa4ConsentScripts(ga4),
+    },
+  ]
+}
+
+function buildGa4ConsentScripts(config: Ga4Config) {
+  const payload = buildGa4Script(config)
+  return [{ src: payload.src, async: true }, { content: payload.init }]
+}

packages/ts-page-scripts/src/authStateHintPlugin.ts

@@ -0,0 +1,23 @@
+import type { PageTemplateInput } from '@purestack/ts-common'
+import { h } from '@purestack/ts-html'
+import { buildAuthStateHintScript } from './buildAuthStateHintScript'
+
+export function authStateHintPlugin() {
+  return {
+    name: 'purestack:auth-state-hint',
+    head({ head, site }: PageTemplateInput) {
+      if (site.auth.enabled && site.auth.signedInStorageKey) {
+        const hint = buildAuthStateHintScript(site.auth.signedInStorageKey)
+        if (hint) {
+          const script = h('script').raw(hint)
+          if (
+            !head.insertBefore('link', script, { rel: 'stylesheet' }) &&
+            !head.insertBefore('script', script)
+          )
+            head.push(script)
+        }
+      }
+      return head
+    },
+  }
+}

packages/ts-page-scripts/src/consentPlugin.ts

@@ -0,0 +1,14 @@
+import type { PageTemplateInput } from '@purestack/ts-common'
+import { h } from '@purestack/ts-html'
+import { buildConsentScript } from './buildConsentScript'
+
+export function consentPlugin() {
+  return {
+    name: 'purestack:consent',
+    head({ head, site }: PageTemplateInput) {
+      if (site.consent.enabled)
+        head.push(h('script').raw(buildConsentScript(site.consent)))
+      return head
+    },
+  }
+}

packages/ts-page-scripts/src/index.ts

@@ -1,6 +1,9 @@
+export { analyticsPlugin } from './analyticsPlugin'
+export { authStateHintPlugin } from './authStateHintPlugin'
 export { buildAuthStateHintScript } from './buildAuthStateHintScript'
 export { buildConsentScript } from './buildConsentScript'
 export { buildThemeSwitchScript } from './buildThemeSwitchScript'
+export { consentPlugin } from './consentPlugin'
 export { buildCodeCopyScript } from './embed/codeCopy.embed'
 export { buildMenuRuntimeScript } from './embed/menuRuntime.embed'
 export { buildModalScript } from './embed/modal.embed'

packages/ts-page-scripts/src/plugin.ts

@@ -1,9 +1,6 @@
 import type { PageFrontmatter, RuntimeEmbeds } from '@purestack/ts-common'
 import { isTocEnabled, type PageTemplateInput } from '@purestack/ts-common'
 import { h } from '@purestack/ts-html'
-import { buildAuthStateHintScript } from './buildAuthStateHintScript'
-import { buildConsentScript } from './buildConsentScript'
-import { buildGa4Script } from './buildGa4Script'
 import { buildCodeCopyScript } from './embed/codeCopy.embed'
 import { buildMenuRuntimeScript } from './embed/menuRuntime.embed'
 import { buildNavMenuScript } from './embed/navMenu.embed'
@@ -41,28 +38,6 @@ function renderScriptsHead({
   pageInfo,
   outline,
 }: PageTemplateInput) {
-  if (config.auth.enabled && config.auth.signedInStorageKey) {
-    const hint = buildAuthStateHintScript(config.auth.signedInStorageKey)
-    if (hint) {
-      const auth = h('script').raw(hint)
-      // The hint must run before stylesheet loading can delay other scripts.
-      if (
-        !head.insertBefore('link', auth, { rel: 'stylesheet' }) &&
-        !head.insertBefore('script', auth)
-      )
-        head.push(auth)
-    }
-  }
-  if (config.consent.enabled)
-    head.push(h('script').raw(buildConsentScript(config.consent)))
-  const ga4 = config.analytics.ga4
-  if (ga4.enabled && ga4.measurementId && !config.consent.enabled) {
-    const payload = buildGa4Script(ga4)
-    head.push(
-      h('script').attr({ async: 'true', src: payload.src }),
-      h('script').raw(payload.init),
-    )
-  }
   head.push(h('script').raw(buildMenuRuntimeScript()))
   if (pageInfo.frontmatter.layout.showNav !== false)
     head.push(h('script').raw(buildNavMenuScript()))

packages/ts-page-scripts/src/runtimeScripts.test.ts

@@ -6,20 +6,21 @@ import { appendRuntimeScripts } from './runtimeScripts'
 
 describe('appendRuntimeScripts', () => {
   it('supports standalone rendering through the generic renderer callback', async () => {
+    const context: Partial<PageContext> = { recordRuntimeEmbed: () => {} }
     const output = await renderApp(
       '<html><head></head><body><p>Standalone</p></body></html>',
       {
         components: {},
-        context: { recordRuntimeEmbed: () => {} } as PageContext,
+        context: context as PageContext,
         onRendered: (document, runtimeEmbeds) =>
           appendRuntimeScripts(document, runtimeEmbeds, { tabs: 'body' }),
       },
     )
     expect(output).toContain('<p>Standalone</p>')
     expect(output).toContain('tsSsgTabs')
   })
-  it('preserves script order and lets recorded placement override frontmatter', async () => {
-    await runInDom('<html><head></head><body></body></html>', (document) => {
+  it('preserves script order and lets recorded placement override frontmatter', () => {
+    runInDom('<html><head></head><body></body></html>', (document) => {
       appendRuntimeScripts(
         document,
         new Map([
@@ -39,8 +40,8 @@ describe('appendRuntimeScripts', () => {
     })
   })
 
-  it('supports explicit frontmatter embeds without rendered components', async () => {
-    await runInDom('<html><head></head><body></body></html>', (document) => {
+  it('supports explicit frontmatter embeds without rendered components', () => {
+    runInDom('<html><head></head><body></body></html>', (document) => {
       appendRuntimeScripts(document, new Map(), { tabs: 'body', modal: 'body' })
       const scripts = [...document.body.querySelectorAll('script')]
       expect(scripts).toHaveLength(2)