@pagesmith/docs 0.1.0

package/theme/runtime/toc-highlight.ts

@@ -0,0 +1,73 @@
+/**
+ * Active TOC highlighting via IntersectionObserver.
+ *
+ * Progressive enhancement — TOC works without this, but with JS
+ * the currently visible section gets highlighted in the right sidebar.
+ * When the active heading changes, the TOC scrolls to keep it visible.
+ */
+
+export function initTocHighlight(): void {
+  const tocLinks = document.querySelectorAll<HTMLAnchorElement>('.doc-aside .doc-toc-item a')
+  if (tocLinks.length === 0) return
+
+  const headingIds = Array.from(tocLinks)
+    .map((a) => a.getAttribute('href')?.slice(1))
+    .filter((id): id is string => !!id)
+
+  const headings = headingIds
+    .map((id) => document.getElementById(id))
+    .filter((el): el is HTMLElement => el !== null)
+
+  if (headings.length === 0) return
+
+  // Track which headings are currently visible
+  const visibleIds = new Set<string>()
+  let currentId = ''
+
+  function updateActive() {
+    const prevId = currentId
+    // Pick the first heading in document order that is visible
+    currentId = ''
+    for (const id of headingIds) {
+      if (visibleIds.has(id)) {
+        currentId = id
+        break
+      }
+    }
+    // Update TOC active state
+    tocLinks.forEach((link) => {
+      const li = link.parentElement
+      if (li) {
+        li.classList.toggle('active', link.getAttribute('href') === `#${currentId}`)
+      }
+    })
+    // Scroll active TOC item into view when it changes
+    if (currentId !== prevId) {
+      const activeLi = document.querySelector(
+        '.doc-aside .doc-toc-item.active',
+      ) as HTMLElement | null
+      if (activeLi) {
+        activeLi.scrollIntoView({ block: 'nearest', behavior: 'smooth' })
+      }
+    }
+  }
+
+  const observer = new IntersectionObserver(
+    (entries) => {
+      for (const entry of entries) {
+        if (entry.isIntersecting) {
+          visibleIds.add(entry.target.id)
+        } else {
+          visibleIds.delete(entry.target.id)
+        }
+      }
+      updateActive()
+    },
+    {
+      rootMargin: '-80px 0px -40% 0px',
+      threshold: 0,
+    },
+  )
+
+  headings.forEach((h) => observer.observe(h))
+}

package/theme/styles/code/inline.css

@@ -0,0 +1,26 @@
+/* ═══════════════════════════════════════════════════════════════
+   Inline code styling
+   ═══════════════════════════════════════════════════════════════ */
+
+/* ─── Inline code ─── */
+.prose code {
+  font-family: var(--font-mono);
+  font-size: 0.875em;
+  padding: 0.15em 0.4em;
+  background: var(--color-code-bg);
+  color: var(--color-code-text);
+  border-radius: var(--radius-sm);
+  word-break: break-word;
+  white-space: normal;
+}
+/* Reset for code inside pre blocks */
+.prose pre code {
+  padding: 0;
+  background: none;
+  color: inherit;
+  border-radius: 0;
+  white-space: pre;
+  font-size: var(--font-size-sm);
+  line-height: 1.7;
+  word-break: normal;
+}

package/theme/styles/components/not-found.css

@@ -0,0 +1,85 @@
+/* 404 Not Found page */
+
+.doc-not-found {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 5rem 0;
+}
+
+.doc-not-found-container {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  text-align: center;
+}
+
+.doc-not-found-code {
+  font-size: 8rem;
+  font-weight: 300;
+  line-height: 1;
+  color: var(--color-text-muted);
+  opacity: 0.5;
+}
+
+.doc-not-found-title {
+  margin-top: 0.75rem;
+  font-size: 1.75rem;
+  font-weight: 400;
+  color: var(--color-text);
+}
+
+.doc-not-found-text {
+  margin-top: 1.5rem;
+  max-width: 28rem;
+  font-size: 1rem;
+  line-height: 1.6;
+  color: var(--color-text-muted);
+}
+
+.doc-not-found-actions {
+  margin-top: 2.5rem;
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  justify-content: center;
+  gap: 1rem;
+}
+
+.doc-not-found-btn {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.625rem 1.25rem;
+  border-radius: 0.375rem;
+  font-size: 0.875rem;
+  font-weight: 500;
+  text-decoration: none;
+  transition:
+    background-color var(--transition-fast),
+    border-color var(--transition-fast),
+    color var(--transition-fast);
+}
+
+.doc-not-found-btn-primary {
+  background-color: var(--color-accent);
+  color: var(--color-text-inverse);
+}
+.doc-not-found-btn-primary:hover {
+  background-color: var(--color-accent-hover);
+  opacity: 0.9;
+}
+
+@media (max-width: 800px) {
+  .doc-not-found {
+    padding: 3rem 0;
+  }
+
+  .doc-not-found-code {
+    font-size: 6rem;
+  }
+
+  .doc-not-found-title {
+    font-size: 1.5rem;
+  }
+}

package/theme/styles/components/search.css

@@ -0,0 +1,300 @@
+/* ═══════════════════════════════════════════════════════════════
+   Search trigger button (header) + modal dialog + Pagefind overrides
+   ═══════════════════════════════════════════════════════════════ */
+
+/* ─── Trigger button in header ─── */
+.doc-search-trigger {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.375rem 0.625rem;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-md);
+  background: var(--color-bg-elevated);
+  color: var(--color-text-muted);
+  cursor: pointer;
+  font-size: var(--font-size-sm);
+  line-height: 1;
+  flex-shrink: 0;
+  transition: border-color var(--transition-fast), color var(--transition-fast);
+}
+.doc-search-trigger:hover {
+  border-color: var(--color-text-muted);
+  color: var(--color-text);
+}
+
+.doc-search-icon {
+  display: flex;
+  align-items: center;
+}
+.doc-search-icon svg {
+  width: 16px;
+  height: 16px;
+}
+
+/* Keyboard shortcut badge — hidden on mobile */
+.doc-search-shortcut {
+  display: none;
+  align-items: center;
+  gap: 0.0625rem;
+  font-family: inherit;
+  font-size: var(--font-size-xs);
+  color: var(--color-text-muted);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-sm);
+  padding: 0.0625rem 0.3rem;
+  line-height: 1.3;
+}
+@media (min-width: 640px) {
+  .doc-search-shortcut {
+    display: flex;
+  }
+}
+
+/* ─── Modal dialog ─── */
+.doc-search-modal {
+  padding: 0;
+  border: none;
+  border-radius: var(--radius-lg);
+  background: var(--color-bg);
+  box-shadow: 0 20px 48px rgba(15, 23, 42, 0.18);
+  max-width: 640px;
+  width: calc(100% - 2rem);
+  max-height: 80vh;
+  margin: 10vh auto;
+}
+.doc-search-modal::backdrop {
+  background: var(--color-overlay-bg);
+}
+
+.doc-search-modal-inner {
+  display: flex;
+  flex-direction: column;
+  max-height: 80vh;
+}
+
+.doc-search-modal-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.75rem 1.25rem;
+  border-bottom: 1px solid var(--color-border-subtle);
+}
+
+.doc-search-modal-title {
+  font-size: var(--font-size-sm);
+  font-weight: 600;
+  color: var(--color-text-secondary);
+}
+
+.doc-search-modal-close {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 28px;
+  height: 28px;
+  padding: 0;
+  border: none;
+  border-radius: var(--radius-sm);
+  background: transparent;
+  color: var(--color-text-muted);
+  cursor: pointer;
+  transition: color var(--transition-fast), background var(--transition-fast);
+}
+.doc-search-modal-close:hover {
+  color: var(--color-text);
+  background: var(--color-bg-hover);
+}
+.doc-search-modal-close svg {
+  width: 16px;
+  height: 16px;
+}
+
+.doc-search-modal-body {
+  padding: 1rem 1.25rem;
+  overflow-y: auto;
+  flex: 1;
+}
+
+/* ═══════════════════════════════════════════════════════════════
+   Pagefind UI overrides — force site fonts + match docs theme
+   ═══════════════════════════════════════════════════════════════ */
+
+.doc-search-modal .pagefind-ui {
+  --pagefind-ui-scale: 0.9;
+  --pagefind-ui-primary: var(--color-text);
+  --pagefind-ui-text: var(--color-text-secondary);
+  --pagefind-ui-background: var(--color-bg-elevated);
+  --pagefind-ui-border: var(--color-border-subtle);
+  --pagefind-ui-tag: var(--color-bg-hover);
+  --pagefind-ui-border-width: 1px;
+  --pagefind-ui-border-radius: var(--radius-md);
+  --pagefind-ui-image-border-radius: var(--radius-md);
+  --pagefind-ui-font: var(--font-sans);
+}
+
+/* Force site font on all Pagefind elements (override reset's all:unset) */
+.doc-search-modal .pagefind-ui,
+.doc-search-modal .pagefind-ui *,
+.doc-search-modal .pagefind-ui *::before,
+.doc-search-modal .pagefind-ui *::after {
+  font-family: var(--font-sans) !important;
+}
+
+/* ─── Search input ─── */
+.doc-search-modal .pagefind-ui__search-input {
+  min-height: 40px;
+  font-weight: 500;
+  font-size: calc(16px * var(--pagefind-ui-scale));
+  color: var(--color-text);
+  background: var(--color-bg-elevated);
+  border-color: var(--color-border);
+  border-radius: var(--radius-md);
+  transition: border-color var(--transition-fast);
+}
+.doc-search-modal .pagefind-ui__search-input:focus {
+  border-color: var(--color-border-hover);
+  outline: none;
+}
+.doc-search-modal .pagefind-ui__search-input::placeholder {
+  color: var(--color-text-muted);
+  opacity: 0.6;
+}
+
+/* ─── Search clear button ─── */
+.doc-search-modal .pagefind-ui__search-clear {
+  color: var(--color-text-muted);
+  font-size: var(--font-size-xs);
+  font-weight: 500;
+  background: var(--color-bg-elevated);
+  border-radius: var(--radius-sm);
+  transition: color var(--transition-fast);
+}
+.doc-search-modal .pagefind-ui__search-clear:hover {
+  color: var(--color-text);
+}
+
+/* ─── Drawer / results area ─── */
+.doc-search-modal .pagefind-ui__drawer {
+  box-shadow: none;
+  margin-top: 0.5rem;
+}
+
+/* ─── Result message (e.g. "3 results for ...") ─── */
+.doc-search-modal .pagefind-ui__message {
+  font-weight: 600;
+  font-size: var(--font-size-sm);
+  color: var(--color-text-muted);
+}
+
+/* ─── Result items ─── */
+.doc-search-modal .pagefind-ui__result {
+  border-color: var(--color-border-subtle);
+  padding: 0.875rem 0;
+}
+
+/* ─── Result title + link ─── */
+.doc-search-modal .pagefind-ui__result-title {
+  font-size: var(--font-size-base);
+  font-weight: 600;
+  color: var(--color-text);
+}
+.doc-search-modal .pagefind-ui__result-link {
+  color: var(--color-text) !important;
+  text-decoration: none !important;
+  transition: color var(--transition-fast);
+}
+.doc-search-modal .pagefind-ui__result-link:hover {
+  text-decoration: underline !important;
+  text-decoration-color: var(--color-border) !important;
+  text-underline-offset: 2px;
+}
+
+/* ─── Result excerpt ─── */
+.doc-search-modal .pagefind-ui__result-excerpt {
+  font-size: var(--font-size-sm);
+  font-weight: 400;
+  color: var(--color-text-secondary);
+  line-height: 1.6;
+}
+.doc-search-modal .pagefind-ui__result-excerpt mark {
+  background: transparent;
+  color: var(--color-text);
+  font-weight: 600;
+}
+
+/* ─── Result tags ─── */
+.doc-search-modal .pagefind-ui__result-tag {
+  font-size: var(--font-size-xs);
+  font-weight: 500;
+  color: var(--color-text-muted);
+  background: var(--color-bg-hover);
+  border-radius: var(--radius-sm);
+}
+
+/* ─── Nested sub-results ─── */
+.doc-search-modal .pagefind-ui__result-nested .pagefind-ui__result-link {
+  font-size: var(--font-size-sm) !important;
+  color: var(--color-text-secondary) !important;
+}
+.doc-search-modal .pagefind-ui__result-nested .pagefind-ui__result-link:hover {
+  color: var(--color-text) !important;
+}
+
+/* ─── Load more button ─── */
+.doc-search-modal .pagefind-ui__button {
+  font-size: var(--font-size-sm);
+  font-weight: 600;
+  color: var(--color-text-secondary);
+  background: var(--color-bg);
+  border-color: var(--color-border);
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  transition: border-color var(--transition-fast), color var(--transition-fast);
+}
+.doc-search-modal .pagefind-ui__button:hover {
+  color: var(--color-text);
+  border-color: var(--color-border-hover);
+  background: var(--color-bg);
+}
+
+/* ─── Filter panel ─── */
+.doc-search-modal .pagefind-ui__filter-panel {
+  font-size: var(--font-size-sm);
+}
+.doc-search-modal .pagefind-ui__filter-name {
+  font-weight: 600;
+  font-size: var(--font-size-sm);
+  color: var(--color-text);
+}
+.doc-search-modal .pagefind-ui__filter-label {
+  font-size: var(--font-size-sm);
+  font-weight: 400;
+  color: var(--color-text-secondary);
+}
+.doc-search-modal .pagefind-ui__filter-checkbox {
+  border-color: var(--color-border);
+  background: var(--color-bg-elevated);
+  border-radius: var(--radius-sm);
+}
+.doc-search-modal .pagefind-ui__filter-checkbox:checked {
+  background: var(--color-accent);
+  border-color: var(--color-accent);
+}
+
+/* ─── Loading skeleton ─── */
+.doc-search-modal .pagefind-ui__loading {
+  background-color: var(--color-text-muted);
+  border-radius: var(--radius-sm);
+}
+
+/* ─── Responsive ─── */
+@media (max-width: 640px) {
+  .doc-search-modal {
+    margin: 2rem auto;
+    max-height: calc(100vh - 4rem);
+  }
+  .doc-search-modal-inner {
+    max-height: calc(100vh - 4rem);
+  }
+}

package/theme/styles/content/alerts.css

@@ -0,0 +1,87 @@
+/* ═══════════════════════════════════════════════════════════════
+   GitHub-style alerts — > [!NOTE], > [!TIP], > [!IMPORTANT],
+   > [!WARNING], > [!CAUTION]
+   ═══════════════════════════════════════════════════════════════ */
+
+.markdown-alert {
+  padding: 0.75rem 1rem;
+  margin: 1.25rem 0;
+  border-left: 4px solid var(--alert-color, var(--color-border-subtle));
+  border-radius: var(--radius-sm);
+  background: var(--alert-bg, var(--color-bg-alt));
+}
+
+.markdown-alert > :first-child { margin-top: 0; }
+.markdown-alert > :last-child { margin-bottom: 0; }
+
+.markdown-alert-title {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  font-weight: 600;
+  font-size: 0.875rem;
+  margin-bottom: 0.25rem;
+  color: var(--alert-color, var(--color-text));
+}
+
+/* Octicon SVG via CSS mask */
+.octicon {
+  display: inline-block;
+  width: 1em;
+  height: 1em;
+  flex-shrink: 0;
+  background-color: currentColor;
+  mask-image: var(--oct-icon);
+  mask-size: contain;
+  mask-repeat: no-repeat;
+  -webkit-mask-image: var(--oct-icon);
+  -webkit-mask-size: contain;
+  -webkit-mask-repeat: no-repeat;
+}
+
+/* ─── Alert variants ─── */
+
+.markdown-alert-note {
+  --alert-color: #0969da;
+  --alert-bg: color-mix(in srgb, #0969da 6%, transparent);
+}
+.markdown-alert-tip {
+  --alert-color: #1a7f37;
+  --alert-bg: color-mix(in srgb, #1a7f37 6%, transparent);
+}
+.markdown-alert-important {
+  --alert-color: #8250df;
+  --alert-bg: color-mix(in srgb, #8250df 6%, transparent);
+}
+.markdown-alert-warning {
+  --alert-color: #9a6700;
+  --alert-bg: color-mix(in srgb, #9a6700 6%, transparent);
+}
+.markdown-alert-caution {
+  --alert-color: #d1242f;
+  --alert-bg: color-mix(in srgb, #d1242f 6%, transparent);
+}
+
+/* ─── Dark mode ─── */
+@media (prefers-color-scheme: dark) {
+  .markdown-alert-note {
+    --alert-color: #4493f8;
+    --alert-bg: color-mix(in srgb, #4493f8 8%, transparent);
+  }
+  .markdown-alert-tip {
+    --alert-color: #3fb950;
+    --alert-bg: color-mix(in srgb, #3fb950 8%, transparent);
+  }
+  .markdown-alert-important {
+    --alert-color: #a371f7;
+    --alert-bg: color-mix(in srgb, #a371f7 8%, transparent);
+  }
+  .markdown-alert-warning {
+    --alert-color: #d29922;
+    --alert-bg: color-mix(in srgb, #d29922 8%, transparent);
+  }
+  .markdown-alert-caution {
+    --alert-color: #f85149;
+    --alert-bg: color-mix(in srgb, #f85149 8%, transparent);
+  }
+}