Runtime

@pagesmith/site provides pre-built CSS and JS assets for styling rendered markdown content. This page is the comprehensive guide for CSS imports, runtime JavaScript, design tokens, and customization across Vite sites and framework-hosted apps such as Next.js.

Notice standalone is a superset of the content tier (same markdown and code chrome) plus TOC, grid, and sidebar layout.

CSS Export Paths

Pagesmith provides four CSS export paths that can be imported directly in Vite projects or any framework/bundler that supports package exports:

Importing CSS in App Code

Import CSS directly in your entry file, theme stylesheet, or framework app layout:

1@import '@pagesmith/site/css/fonts';2@import '@pagesmith/site/css/content';

Or import from JavaScript/TypeScript:

1import "@pagesmith/site/css/fonts";2import "@pagesmith/site/css/content";

In a Next.js App Router project, the equivalent is a global import from app/layout.js plus a tiny client component for the runtime:

1"use client";23import "@pagesmith/site/runtime/content";45export function PagesmithContentRuntime() {6  return null;7}

For a full documentation layout:

1@import '@pagesmith/site/css/fonts';2@import '@pagesmith/site/css/standalone';

CSS File Contents

@pagesmith/site/css/content (Content Tier)

The content CSS bundle includes everything needed for styled markdown output without any layout:

1foundations/reset.css       CSS reset2foundations/color-scheme.css Color-scheme classes3foundations/tokens.css      Design tokens as custom properties4foundations/themes.css      Theme variant overrides5content/prose.css           Typography for rendered markdown6content/alerts.css          GitHub Alerts / callout styling7code/block.css              Code block frame, line, and copy styles8code/inline.css             Inline code styling9code/tabs.css               Tab chrome for grouped code blocks10viewport.css                Viewport overflow protection

Code block styling is included in the shared CSS bundle. Shiki token colors still arrive inline per block, but the frame chrome, line layout, copy button styling, and tabs come from the shipped Pagesmith CSS.

@pagesmith/site/css/standalone (Standalone Tier)

The standalone CSS bundle adds layout components on top of the content tier:

1chrome.css                  Shared shell chrome (TOC, page meta, viewport, grid, header, sidebar, footer, listing, search, theme toggle)2content/prose.css           Typography for rendered markdown3content/alerts.css          GitHub Alerts / callout styling4code/block.css              Code block frame, line, and copy styles5code/inline.css             Inline code styling6code/tabs.css               Tab chrome for grouped code blocks

@pagesmith/site/css/viewport

Minimal viewport and responsive base styles. Useful when you only need overflow protection without the full content or standalone bundles.

@pagesmith/site/css/fonts

Font face declarations for the two bundled variable fonts:

• Open Sans (variable, 300-800 weight) — used for body text (--font-sans)
• JetBrains Mono (variable, 400-700 weight) — used for code (--font-mono)

The font files are distributed as woff2 in the @pagesmith/site/assets/fonts/ directory. The fonts.css file references them with relative URLs.

How Pagesmith Handles Code Block CSS

Pagesmith splits code block rendering into two layers:

• Shared CSS bundles provide frame chrome, line layout, tabs, diff markers, and button styling.
• The renderer adds inline theme variables for syntax token colors and per-block light/dark backgrounds.
• The shared Pagesmith content runtime enables tabs, copy, and collapse interactions.

If you want to customize code block appearance, override the --ps-* custom properties or target the Pagesmith code block classes in your own stylesheet.

Runtime JS Accessor Functions

The @pagesmith/site/runtime module provides functions that read pre-built CSS and JS files for server-side rendering scenarios where you need to inline assets or reference file paths.

Chrome Tier (Shared Shell)

For projects that want the reusable site chrome without the full standalone shell helpers:

Standalone Tier (Full Site)

For projects that want a complete page layout with navigation, table of contents, and interactive features:

Content Tier (Markdown Rendering Only)

For projects that already have their own layout but want consistent styling for rendered markdown:

Individual CSS Files

All accessor functions read from the @pagesmith/site package directory, checking src/ first (for development with linked packages) and falling back to dist/ (for published builds).

Runtime JavaScript Behavior

Standalone Runtime

The standalone runtime adds the full Pagesmith site enhancements on top of the content runtime:

• Footer year sync (footer-year.ts) — updates copyright year when the rendered site spans calendar years.
• Search trigger density (search-trigger.ts) — collapses the Pagefind trigger on small screens.
• Sidebar modal (sidebar.ts) — drives the mobile <dialog> navigation, including focus management and close targets.
• Skip-link focus (skip-link.ts) — preserves accessible keyboard navigation back to main content.
• Theme and text-size controls (theme.ts) — persists appearance, theme, and text-size preferences in localStorage('pagesmith-theme').
• TOC highlight (toc-highlight.ts) — Uses IntersectionObserver with a root margin of -80px 0px -66% 0px to track which heading is near the top of the viewport. When the active heading changes, the corresponding TOC item gets the .active class and is scrolled into view.
• Content runtime behaviors — Copy buttons, code tabs, and collapse toggles for rendered markdown.

The standalone entry is therefore the combination of getChromeJS() plus the content runtime modules.

Content Runtime

The content runtime wires the markdown-specific browser behaviors:

• Code copy buttons — event-delegated click handler copies code block text to clipboard via navigator.clipboard.writeText with legacy execCommand fallback.
• Code tab switching — event-delegated click and keyboard (arrow, Home, End) handlers switch active tab and panel. A MutationObserver on childList auto-activates dynamically added tab containers.
• Collapse / expand toggles — toggles aria-expanded and hidden state on collapsed code line groups.
• Themed image switching — self-contained MutationObserver on the class attribute of <html> with a cached-scheme guard. In auto mode (color-scheme-auto), <picture> media queries handle light/dark natively — zero JS cost. In forced mode (color-scheme-light/color-scheme-dark), sources are stripped to the matching set. Unrelated class changes (text-size, theme palette) are a single classList.contains() check with no DOM mutations.

It intentionally does not own your app shell, navigation, TOC implementation, or theme controls. That makes it a good fit for framework-hosted apps that already have their own layout and routing.

Granular Runtime Entries

For advanced integrations, @pagesmith/site also exposes narrower browser entries that map to specific behaviors:

Use these when you want to assemble your own browser runtime instead of taking the full content, chrome, or standalone bundle. The themed-image switcher is not exposed as a standalone entry — it ships as part of the chrome, content, and standalone bundles.

Progressive Enhancement

The runtime JavaScript is strictly a progressive enhancement layer. All content is readable without JavaScript. Copy buttons, code tabs, collapse controls, and themed images all render in the HTML output during markdown processing, but they need the matching runtime entry point for interactive behavior in forced color-scheme modes.

Design Tokens (CSS Custom Properties)

All visual properties in Pagesmith CSS are defined as CSS custom properties in foundations/tokens.css under :root. The tokens use the CSS light-dark() function for automatic dark mode support, with color-scheme: light dark on :root.

Color Tokens

Shadow Tokens

Shadow colors use dedicated shadow-color tokens with light-dark() for appropriate opacity in each scheme.

Typography Tokens

Spacing and Shape Tokens

Transition Tokens

Layout Token

Customizing Design Tokens

Since all visual properties flow through CSS custom properties, you can retheme the entire runtime by redefining tokens:

1:root {2  --color-accent: light-dark(#0066cc, #66b3ff);3  --font-sans: "Inter", system-ui, sans-serif;4  --radius-md: 8px;5}

For code-block styling and renderer chrome, override the --ps-* prefixed variables:

1:root {2  --ps-font-sans: "Inter", system-ui, sans-serif;3  --ps-font-mono: "Fira Code", monospace;4  --ps-font-size-sm: 0.8rem;5  --ps-radius-lg: 8px;6  --ps-color-border-subtle: light-dark(#e0e0e0, #333333);7}

When to Use Each Tier

When using the runtime programmatically (e.g., for SSR), use the accessor functions from @pagesmith/site/runtime:

1import { getContentCSS, getContentJS } from "@pagesmith/site/runtime";23const css = getContentCSS();4const js = getContentJS();56// Inject into your HTML template7const html = `8  <style>${css}</style>9  <script>${js}</script>10`;

For Vite projects, prefer direct CSS imports over the accessor functions:

1@import '@pagesmith/site/css/fonts';2@import '@pagesmith/site/css/content';