@brillout/docpress 0.16.45 → 0.16.47-commit-cd5aa01

package/EditLink.tsx

@@ -28,11 +28,11 @@ function EditLink({
         paddingBottom: 7,
         paddingLeft: 8,
         paddingRight: 7,
-        border: '1px solid #e0e0e0',
+        border: '1px solid var(--color-border, #e0e0e0)',
         borderRadius: 7,
         fontSize: '0.91em',
-        color: '#6c6c6c',
-        background: '#f8f8f8',
+        color: 'var(--color-muted, #6c6c6c)',
+        background: 'var(--color-surface, #f8f8f8)',
         letterSpacing: 0.4,
         lineHeight: 0,
         ...style,

package/ExternalLinks.tsx

@@ -46,10 +46,11 @@ function ExternalLinks(props: { style?: React.CSSProperties }) {
 
 function ChangelogButton() {
   const pageContext = usePageContext()
-  const { version, github } = pageContext.globalContext.config.docpress
+  const { version, github, changelog } = pageContext.globalContext.config.docpress
+  const changeLogUrl = typeof changelog === 'string' ? changelog : `${github}/blob/main/CHANGELOG.md`
   return (
     <a
-      href={`${github}/blob/main/CHANGELOG.md`}
+      href={changeLogUrl}
       className="colorize-on-hover"
       style={{
         display: 'flex',
@@ -62,7 +63,7 @@ function ChangelogButton() {
         className="button"
         style={{
           background: '#ffffff4f',
-          fontFamily: 'monospace',
+          fontFamily: 'var(--font-mono, monospace)',
           letterSpacing: -1,
           display: 'flex',
           alignItems: 'center',

package/Layout.css

@@ -1,4 +1,3 @@
 body {
   background: var(--color-bg-white);
-  --color-bg-white: #fdfdfd;
 }

package/Layout.tsx

@@ -82,7 +82,7 @@ function Layout({ children }: { children: React.ReactNode }) {
   return (
     <div
       style={{
-        ['--color-bg-gray']: '#f5f5f5',
+        ['--color-bg-gray']: 'var(--color-surface, #f5f5f5)',
         ['--block-margin']: `${blockMargin}px`,
         // ['--nav-head-height']: `${isLandingPage ? 70 : 63}px`,
         ['--nav-head-height']: `63px`,
@@ -94,9 +94,12 @@ function Layout({ children }: { children: React.ReactNode }) {
         margin: 'auto',
       }}
     >
-      <MenuModal isTopNav={isLandingPage} isNavLeftAlwaysHidden_={isNavLeftAlwaysHidden_} />
-      <div className={isLandingPage ? '' : 'doc-page'} style={whitespaceBuster1}>
-        <NavHead />
+      <div className={isLandingPage ? 'landing-page' : 'doc-page'} style={whitespaceBuster1}>
+        <div style={{ position: isLandingPage ? 'relative' : 'sticky', top: 0, zIndex: 100 }}>
+          <NavHead />
+          {/* <MenuModal> is inside here because `container-type` on the page wrapper traps `position: fixed` — https://github.com/brillout/docpress/pull/177 */}
+          <MenuModal isNavLeftAlwaysHidden_={isNavLeftAlwaysHidden_} />
+        </div>
         {content}
       </div>
       {/* Early toggling, to avoid layout jumps */}
@@ -220,10 +223,10 @@ function NavLeft() {
         <div
           style={{
             position: 'sticky',
-            top: 0,
+            // Sit below the sticky top nav
+            top: 'var(--nav-head-height)',
           }}
         >
-          <NavHead isNavLeft={true} />
           <div
             style={{
               backgroundColor: 'var(--color-bg-gray)',
@@ -296,29 +299,18 @@ const menuLinkStyle: React.CSSProperties = {
   justifyContent: 'center',
 }
 
-// Two <NavHead> instances are rendered:
-//  - The left-side <NavHead> shown on documentation pages on desktop
-//  - The top <NavHead> shown otherwise
-function NavHead({ isNavLeft }: { isNavLeft?: true }) {
+function NavHead() {
   const pageContext = usePageContext()
   const { navMaxWidth, name, algolia } = pageContext.globalContext.config.docpress
   const hideNavHeadLogo = pageContext.resolved.isLandingPage && !navMaxWidth
 
   const navHeadSecondary = (
     <div
-      className={cls(['nav-head-secondary', isNavLeft && 'show-on-nav-hover add-transition'])}
+      className="nav-head-secondary"
       style={{
         padding: 0,
         display: 'flex',
         height: '100%',
-        ...(isNavLeft
-          ? {
-              position: 'absolute',
-              left: '100%',
-              top: 0,
-              width: mainViewWidthMax, // guaranteed real estate
-            }
-          : {}),
       }}
     >
       {pageContext.globalContext.config.docpress.topNavigation}
@@ -336,35 +328,38 @@ function NavHead({ isNavLeft }: { isNavLeft?: true }) {
 
   return (
     <div
-      className={cls(['nav-head link-hover-animation', isNavLeft && 'is-nav-left', !!navMaxWidth && 'has-max-width'])}
+      className={cls(['nav-head link-hover-animation', !!navMaxWidth && 'has-max-width'])}
       style={{
         backgroundColor: 'var(--color-bg-gray)',
-        borderBottom: 'var(--block-margin) solid var(--color-bg-white)',
         position: 'relative',
+        boxShadow: `0 ${blockMargin}px 0 var(--color-bg-white)`,
       }}
     >
-      {isNavLeft && <NavHeadLeftFullWidthBackground />}
       <div
         style={{
           // DON'T REMOVE this container: it's needed for the `cqw` values
           container: 'container-nav-head / inline-size',
           width: '100%',
+          // Cap the cqw context so nav-item spacing matches between landing and doc pages.
+          maxWidth: bodyMaxWidth,
+          margin: '0 auto',
         }}
       >
         <div
           className="nav-head-content"
           style={{
             width: '100%',
-            maxWidth: navMaxWidth,
+            // Top nav spans the doc-page width so its logo lines up with the sidebar (same width on landing).
+            maxWidth: bodyMaxWidth,
             margin: 'auto',
             height: 'var(--nav-head-height)',
             fontSize: `min(14.2px, ${isProjectNameShort(name) ? '4.8cqw' : '4.5cqw'})`,
-            color: '#666',
+            color: 'var(--color-muted, #666)',
             display: 'flex',
             justifyContent: 'center',
           }}
         >
-          {!hideNavHeadLogo && <NavHeadLogo isNavLeft={isNavLeft} />}
+          {!hideNavHeadLogo && <NavHeadLogo />}
           <div className="desktop-grow" style={{ display: 'none' }} />
           {algolia && <SearchLink className="always-shown" style={menuLinkStyle} />}
           <MenuToggleMain className="always-shown nav-head-menu-toggle" style={menuLinkStyle} />
@@ -380,7 +375,7 @@ function getStyleLayout() {
   // Mobile
   style += css`
 @media(max-width: ${viewMobile}px) {
-  .nav-head:not(.is-nav-left) {
+  .nav-head {
     .nav-head-menu-toggle {
       justify-content: flex-end !important;
       padding-right: var(--main-view-padding) !important;
@@ -397,7 +392,7 @@ function getStyleLayout() {
   // Mobile + tablet
   style += css`
 @media(max-width: ${viewTablet}px) {
-  .nav-head:not(.is-nav-left) {
+  .nav-head {
     .nav-head-secondary {
       display: none !important;
     }
@@ -407,7 +402,7 @@ function getStyleLayout() {
   // Tablet
   style += css`
 @media(max-width: ${viewTablet}px) and (min-width: ${viewMobile + 1}px) {
-  .nav-head:not(.is-nav-left) {
+  .nav-head {
     .nav-head-content {
       --icon-text-padding: 8px;
       --padding-side: 20px;
@@ -418,7 +413,7 @@ function getStyleLayout() {
   // Desktop small + desktop
   style += css`
 @media(min-width: ${viewTablet + 1}px) {
-  .nav-head:not(.is-nav-left) {
+  .nav-head {
     .nav-head-content {
       --icon-text-padding: min(8px, 0.5cqw);
       --padding-side: min(20px, 1.2cqw);
@@ -442,39 +437,6 @@ function getStyleLayout() {
   // Desktop
   if (!isNavLeftAlwaysHidden()) {
     style += css`
-@container container-viewport (min-width: ${viewDesktop}px) {
-  .nav-head:not(.is-nav-left) {
-    display: none !important;
-  }
-  .nav-head.is-nav-left {
-    .nav-head-content {
-      --icon-text-padding: min(8px, 7 * (1cqw - 2.5px));
-      & > :not(.always-shown) {
-        --padding-side: min(24px, 27 * (1cqw - 2.5px));
-      }
-      & > * {
-        flex-grow: 0.5;
-      }
-      & > .nav-head-menu-toggle {
-        flex-grow: 1;
-      }
-    }
-  }
-  .show-on-nav-hover {
-    opacity: 0;
-    transition-property: opacity;
-    pointer-events: none;
-  }
-  html:not(.unexpand-nav) {
-    & .nav-head.is-nav-left:hover .show-on-nav-hover,
-    &:has(.nav-head:hover) #menu-modal-wrapper.show-on-nav-hover,
-    &.menu-modal-show .nav-head.is-nav-left .show-on-nav-hover,
-    &.menu-modal-show #menu-modal-wrapper.show-on-nav-hover {
-      opacity: 1;
-      pointer-events: all;
-    }
-  }
-}
 @container container-viewport (max-width: ${viewDesktop - 1}px) {
   #nav-left, #nav-left-margin {
     display: none;
@@ -514,37 +476,7 @@ function unexpandNav() {
   }, 1000)
 }
 
-function NavHeadLeftFullWidthBackground() {
-  return (
-    <>
-      <div
-        className="nav-head-bg show-on-nav-hover add-transition"
-        style={{
-          height: '100%',
-          zIndex: -1,
-          background: 'var(--color-bg-gray)',
-          position: 'absolute',
-          left: 0,
-          top: 0,
-          boxSizing: 'content-box',
-          borderBottom: 'var(--block-margin) solid var(--color-bg-white)',
-        }}
-      />
-      <Style>{
-        // (min-width: 0px) => trick to always apply => @container seems to always require a condition
-        css`
-@container container-viewport (min-width: 0px) {
-  .nav-head-bg {
-     width: 100cqw;
-  }
-}
-`
-      }</Style>
-    </>
-  )
-}
-
-function NavHeadLogo({ isNavLeft }: { isNavLeft?: true }) {
+function NavHeadLogo() {
   const pageContext = usePageContext()
 
   const { navLogo } = pageContext.globalContext.config.docpress
@@ -584,14 +516,8 @@ function NavHeadLogo({ isNavLeft }: { isNavLeft?: true }) {
         alignItems: 'center',
         height: '100%',
         color: 'inherit',
-        ...(!isNavLeft
-          ? {
-              paddingLeft: 'var(--main-view-padding)',
-              paddingRight: 'var(--padding-side)',
-            }
-          : {
-              paddingLeft: 15,
-            }),
+        paddingLeft: 'var(--main-view-padding)',
+        paddingRight: 'var(--padding-side)',
       }}
       href="/"
       onContextMenu={!navLogo ? undefined : onContextMenu}
@@ -670,7 +596,7 @@ function MenuToggle({ menuId, ...props }: PropsDiv & { menuId: number }) {
           width: 11,
           marginLeft: 'calc(var(--icon-text-padding) - 1px)',
           flexShrink: 0,
-          color: '#888',
+          color: 'var(--color-muted, #888)',
           position: 'relative',
           top: 1,
         }}

package/MenuModal/NavigationWithColumnLayout.tsx

@@ -138,7 +138,7 @@ function NavigationWithColumnLayout(props: { navItems: NavItem[] }) {
 ${/* Button style */ ''}
 .menu-toggle-${i} {
   html.menu-modal-show.menu-modal-show-${i} & {
-    color: black !important;
+    color: var(--color-text, black) !important;
     [class^='decolorize-'],
     [class*=' decolorize-'] {
       filter: grayscale(0) opacity(1) !important;

package/MenuModal.tsx

@@ -14,7 +14,7 @@ import {
 } from './MenuModal/toggleMenuModal.js'
 import { EditLink } from './EditLink.js'
 
-function MenuModal({ isTopNav, isNavLeftAlwaysHidden_ }: { isTopNav: boolean; isNavLeftAlwaysHidden_: boolean }) {
+function MenuModal({ isNavLeftAlwaysHidden_ }: { isNavLeftAlwaysHidden_: boolean }) {
   return (
     <>
       <Style>{getStyle()}</Style>
@@ -22,11 +22,12 @@ function MenuModal({ isTopNav, isNavLeftAlwaysHidden_ }: { isTopNav: boolean; is
         id="menu-modal-wrapper"
         className="link-hover-animation add-transition show-on-nav-hover"
         style={{
-          position: isTopNav ? 'absolute' : 'fixed',
+          // Absolute inside the sticky header so the dropdown tracks the nav on scroll
+          position: 'absolute',
           width: '100%',
           top: 'var(--nav-head-height)',
           zIndex: 199, // maximum value, because docsearch's modal has `z-index: 200`
-          background: '#ededef',
+          background: 'var(--color-surface, #ededef)',
           transitionProperty: 'opacity',
           transitionTimingFunction: 'ease',
           maxWidth: isNavLeftAlwaysHidden_ ? undefined : bodyMaxWidth,
@@ -169,8 +170,8 @@ function CloseButton({ className }: { className: string }) {
           cx="11.45"
           cy="11.45"
           r="10.607"
-          fill="#ececec"
-          stroke="#666"
+          fill="var(--color-surface, #ececec)"
+          stroke="var(--color-muted, #666)"
           strokeDashoffset="251.44"
           strokeLinecap="round"
           strokeLinejoin="round"
@@ -179,8 +180,8 @@ function CloseButton({ className }: { className: string }) {
         />
         <path
           d="m7.5904 6.2204 3.86 3.86 3.84-3.84a0.92 0.92 0 0 1 0.66-0.29 1 1 0 0 1 1 1 0.9 0.9 0 0 1-0.27 0.66l-3.89 3.84 3.89 3.89a0.9 0.9 0 0 1 0.27 0.61 1 1 0 0 1-1 1 0.92 0.92 0 0 1-0.69-0.27l-3.81-3.86-3.85 3.85a0.92 0.92 0 0 1-0.65 0.28 1 1 0 0 1-1-1 0.9 0.9 0 0 1 0.27-0.66l3.89-3.84-3.89-3.89a0.9 0.9 0 0 1-0.27-0.61 1 1 0 0 1 1-1c0.24 3e-3 0.47 0.1 0.64 0.27z"
-          fill="#666"
-          stroke="#666"
+          fill="var(--color-muted, #666)"
+          stroke="var(--color-muted, #666)"
           strokeWidth=".11719"
         />
       </svg>

package/NavItemComponent.css

@@ -13,7 +13,7 @@
 .nav-item-level-4 {
   padding-top: 14px;
   margin-bottom: -1px;
-  color: #999;
+  color: var(--color-muted, #999);
   font-size: 12px;
   font-weight: 400;
   letter-spacing: 0.15ch;
@@ -82,7 +82,7 @@
 }
 .nav-item-level-3 {
   --shadow-size: 9px;
-  --shadow-color: rgba(0, 0, 0, 0.11);
+  --shadow-color: var(--color-shadow, rgba(0, 0, 0, 0.11));
   --shadow-size-minus: calc(-1 * var(--shadow-size));
   --shadow-top: inset 0px var(--shadow-size) var(--shadow-size) var(--shadow-size-minus) var(--shadow-color);
   --shadow-bottom: inset 0px var(--shadow-size-minus) var(--shadow-size) var(--shadow-size-minus) var(--shadow-color);

package/code-blocks/components/Pre.css

@@ -5,6 +5,7 @@ pre > code {
   */
   background: rgba(0, 0, 0, 0.043137255);
   font-size: 1em;
+  font-family: var(--font-mono, monospace);
 }
 
 /* Copy button */

package/components/HorizontalLine.tsx

@@ -12,7 +12,7 @@ function HorizontalLine({ primary }: { primary?: true }) {
           margin: 0,
           border: 0,
           // Same as `.doc-page h2::after`
-          borderTop: '1px solid rgba(0, 0, 0, 0.1)',
+          borderTop: '1px solid var(--color-border, rgba(0, 0, 0, 0.1))',
           maxWidth: 500,
           width: '80%',
         }}

package/css/code.css

@@ -10,4 +10,5 @@ code {
   border-radius: 4px;
   background: rgba(0, 0, 0, 0.063137255);
   font-size: 1.1em;
+  font-family: var(--font-mono, monospace);
 }

package/css/colorize-on-hover.css

@@ -51,7 +51,11 @@
 }
 
 body {
-  --color-active-value: 0.03;
-  --color-active: rgba(0, 0, 0, var(--color-active-value));
-  --color-active-double: rgba(0, 0, 0, calc(2 * var(--color-active-value)));
+  /* Hover/active tint mixed from the text color so it tracks the active
+     appearance (light text -> light tint on dark). The `#000` fallback makes an
+     unthemed site identical to the original `rgba(0, 0, 0, value)`:
+     color-mix(in srgb, #000 3%, transparent) === rgba(0, 0, 0, 0.03). */
+  --color-active-value: 3%;
+  --color-active: color-mix(in srgb, var(--color-text, #000) var(--color-active-value), transparent);
+  --color-active-double: color-mix(in srgb, var(--color-text, #000) calc(2 * var(--color-active-value)), transparent);
 }

package/css/font.css

@@ -1,13 +1,12 @@
 @import url('https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap');
 
 body {
-  font-family: 'Inter', sans-serif;
+  font-family: var(--font-sans, 'Inter', sans-serif);
 }
 button {
   font-family: inherit;
 }
 body {
-  --color-text: #323d48;
-  color: var(--color-text);
+  color: var(--color-text, #323d48);
   line-height: 1.5;
 }

package/css/heading.css

@@ -13,6 +13,11 @@ h3 {
   margin-bottom: 20px;
 }
 
+/* Offset headings below the sticky top nav. */
+.doc-page :is(h1, h2, h3, h4, h5, h6) {
+  scroll-margin-top: calc(var(--nav-head-height) + 16px);
+}
+
 .doc-page h2,
 .doc-page h3 {
   margin-bottom: 16px;
@@ -27,7 +32,7 @@ h3 {
   height: 1px;
   top: -45px;
   /* Same as <HorizontalLine> */
-  background-color: rgba(0, 0, 0, 0.1);
+  background-color: var(--color-border, rgba(0, 0, 0, 0.1));
   --width: min(80%, 500px);
   width: var(--width);
   left: calc((100% - var(--width)) / 2);
@@ -54,7 +59,7 @@ h3 {
 
 .doc-page h5 {
   font-size: 0.94em;
-  color: #777;
+  color: var(--color-muted, #777);
   margin-bottom: 10px;
 }
 
@@ -82,7 +87,7 @@ h3 {
     font-size: 23px;
     top: 1px;
     left: calc(-1 * (0.75em - var(--hash-offset)));
-    color: #aaa;
+    color: var(--color-muted, #aaa);
     display: flex;
     align-items: center;
   }

package/css/index.css

@@ -1,3 +1,4 @@
+@import './tokens.css';
 @import './reset.css';
 @import './colorize-on-hover.css';
 @import './heading.css';

package/css/link.css

@@ -2,5 +2,5 @@ a {
   text-decoration: none;
 }
 .doc-page a[href]:not(.nav-item) {
-  color: #4747ff;
+  color: var(--color-primary, #4747ff);
 }

package/css/table.css

@@ -1,5 +1,5 @@
 table th {
-  background-color: #f7f7f7;
+  background-color: var(--color-surface, #f7f7f7);
 }
 table {
   border-collapse: collapse;
@@ -7,7 +7,7 @@ table {
 table td,
 table th {
   padding: 8px;
-  border: 1px solid #ccc;
+  border: 1px solid var(--color-border, #ccc);
 }
 table th {
   text-align: left;

package/css/tokens.css

@@ -0,0 +1,34 @@
+/*
+ * Color tokens (opt-in, zero default change).
+ *
+ * No light palette is defined here on purpose: every consumer reads
+ * `var(--color-x, <literal>)` and falls back to its original literal, so an
+ * unthemed DocPress site renders exactly as before. A site re-themes by setting
+ * the `--color-*` variables (on :root or body), and turns on a dark appearance
+ * by adding the `dark` class or `[data-theme="dark"]`. There is no
+ * `prefers-color-scheme` switch, so the OS setting never changes a site that
+ * has not opted in.
+ */
+:root {
+  /* --color-text has a single original value and pre-existing consumers that
+     read it bare (nav items, tabs), so it is defined here (was `body {}`). It
+     stays overridable (a `body`/`:root` override or the dark block below wins).
+     The ambiguous greys are intentionally NOT defined here: their consumers fall
+     back to their own original literal, so light rendering is unchanged. */
+  --color-text: #323d48;
+
+  /* Long-standing internal aliases, kept resolving to their original defaults. */
+  --color-bg-white: var(--color-bg, #fdfdfd);
+  --color-bg-gray: var(--color-surface, #f5f5f5);
+}
+
+:root.dark,
+:root[data-theme='dark'] {
+  --color-bg: #0d0f14;
+  --color-surface: #161922;
+  --color-text: #d7dce5;
+  --color-muted: #8b95a5;
+  --color-border: #2b313c;
+  --color-primary: #8aa0ff;
+  --color-shadow: rgba(0, 0, 0, 0.45);
+}

package/css/tooltip.css

@@ -13,19 +13,19 @@
     opacity: 0;
     transition: opacity 0.3s ease-in-out;
     pointer-events: none;
-    font-family: monospace;
+    font-family: var(--font-mono, monospace);
     font-size: 12px;
     content: attr(aria-label);
     position: absolute;
     left: 50%;
     transform: translate(-50%, 0);
-    background: #fdfdfd;
+    background: var(--color-bg, #fdfdfd);
     padding: 3px 10px;
-    box-shadow: rgb(0 0 0 / 8%) 2px 4px 7px 0px;
+    box-shadow: var(--color-shadow, rgb(0 0 0 / 8%)) 2px 4px 7px 0px;
     border-radius: 5px;
-    color: #333;
+    color: var(--color-text, #333);
     letter-spacing: -0.02em;
-    border: 1px solid #e3e3e3;
+    border: 1px solid var(--color-border, #e3e3e3);
     z-index: 1;
     /* Atlernative: https://stackoverflow.com/questions/30086913/css-positioned-absolute-element-automatic-width-outside-of-parents-bounds/57379329#57379329
     width: max-content;

package/dist/components/HorizontalLine.js

@@ -8,7 +8,7 @@ function HorizontalLine({ primary }) {
                 margin: 0,
                 border: 0,
                 // Same as `.doc-page h2::after`
-                borderTop: '1px solid rgba(0, 0, 0, 0.1)',
+                borderTop: '1px solid var(--color-border, rgba(0, 0, 0, 0.1))',
                 maxWidth: 500,
                 width: '80%',
             } })));

package/dist/types/Config.d.ts

@@ -13,12 +13,23 @@ type Config = {
         google: string;
     };
     banner?: string;
+    /**
+     * Raw HTML injected at the end of `<head>` on every page.
+     *
+     * Use for a small inline `<script>`/`<style>` that must run before first
+     * paint — e.g. a no-flash theme script that reads a cookie and applies the
+     * palette before the page renders (relevant for prerendered/static pages,
+     * where there is no request to read the cookie from at render time).
+     *
+     * Emitted verbatim (not escaped), so only pass trusted, self-authored markup.
+     */
+    headHtml?: string;
     github: string;
     discord?: string;
     twitter?: string;
     bluesky?: string;
     linkedin?: string;
-    changelog?: boolean;
+    changelog?: boolean | string;
     headings: HeadingDefinition[];
     headingsDetached: HeadingDetachedDefinition[];
     categories?: Category[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brillout/docpress",
-  "version": "0.16.45",
+  "version": "0.16.47-commit-cd5aa01",
   "type": "module",
   "dependencies": {
     "@brillout/picocolors": "^1.0.10",

package/renderer/onRenderHtml.tsx

@@ -30,6 +30,7 @@ async function onRenderHtml(pageContext: PageContextServer): Promise<any> {
         <meta name="viewport" content="width=device-width,initial-scale=1">
         ${getOpenGraphTags(pageContext.urlPathname, documentTitle, pageContext.globalContext.config.docpress)}
         ${getAlgoliaTags(pageContext)}
+        ${getHeadHtml(pageContext.globalContext.config.docpress)}
       </head>
       <body>
         <div id="page-view">${dangerouslySkipEscape(pageHtml)}</div>
@@ -37,6 +38,10 @@ async function onRenderHtml(pageContext: PageContextServer): Promise<any> {
     </html>`
 }
 
+function getHeadHtml(config: Config) {
+  return config.headHtml ? dangerouslySkipEscape(config.headHtml) : ''
+}
+
 function getAlgoliaTags(pageContext: PageContextServer) {
   const activeCategory = getActiveCategory(pageContext)
   const categoryNameTag = escapeInject`<meta name="algolia:category" content="${activeCategory.name}">`

package/types/Config.ts

@@ -18,12 +18,24 @@ type Config = {
       }
   banner?: string
 
+  /**
+   * Raw HTML injected at the end of `<head>` on every page.
+   *
+   * Use for a small inline `<script>`/`<style>` that must run before first
+   * paint — e.g. a no-flash theme script that reads a cookie and applies the
+   * palette before the page renders (relevant for prerendered/static pages,
+   * where there is no request to read the cookie from at render time).
+   *
+   * Emitted verbatim (not escaped), so only pass trusted, self-authored markup.
+   */
+  headHtml?: string
+
   github: string
   discord?: string
   twitter?: string
   bluesky?: string
   linkedin?: string
-  changelog?: boolean
+  changelog?: boolean | string
 
   headings: HeadingDefinition[]
   headingsDetached: HeadingDetachedDefinition[]