coherent-docs-theme 1.0.0

package/remark-directives/internal.ts

@@ -0,0 +1,20 @@
+import { visit } from 'unist-util-visit';
+import type { Root } from 'mdast';
+
+export function remarkInternalDirective() {
+    return (tree: Root) => {
+        visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node: any, index, parent) => {
+            const nodeName = node.name;
+            if (nodeName !== 'Internal' || index === undefined || !parent) return;
+            const isDev = process.env.MODE === 'development' || process.env.NODE_ENV === 'development';
+
+            if (isDev) {
+                parent.children.splice(index, 1, ...node.children);
+                return index;
+            } else {
+                parent.children.splice(index, 1);
+                return index;
+            }
+        });
+    };
+}

package/remark-directives/release.ts

@@ -0,0 +1,29 @@
+import { visit } from 'unist-util-visit';
+import type { Root } from 'mdast';
+
+export function remarkReleaseDirective() {
+    return (tree: Root) => {
+        visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node: any, index, parent) => {
+            const nodeName = node.name;
+            if (nodeName !== 'Release' || index === undefined || !parent) return;
+
+            const attrs = Object.fromEntries(node.attributes?.map((a: any) => [a.name, a.value]) || []);
+            const { version } = attrs;
+
+            if (!version) return;
+
+            const headingNode = {
+                type: 'heading',
+                depth: 2,
+                children: [{ type: 'text', value: `Version ${version}` }],
+                data: {
+                    hProperties: { id: version }
+                }
+            };
+
+            parent.children.splice(index, 0, headingNode);
+
+            return index + 2;
+        });
+    };
+}

package/styles.css

@@ -0,0 +1,452 @@
+@import url('https://fonts.googleapis.com/css2?family=Barlow+Semi+Condensed:wght@400;600;700&family=Karla:wght@400;700&display=swap');
+
+@layer starlight, coh-theme;
+
+@layer coh-theme {
+
+  /* ========================================= */
+  /* 1. GLOBAL VARIABLES & DARK THEME (DEFAULT) */
+  /* ========================================= */
+  :root {
+    --pagefind-ui-scale: 0.9;
+
+    /* --- Shared Settings (Typography & Shapes) --- */
+    --sl-font: 'Karla', sans-serif;
+    --sl-font-system: 'Karla', sans-serif;
+    --sl-font-heading: 'Barlow Semi Condensed', sans-serif;
+
+    /* Layout */
+    --sl-content-width: 80%;
+    --sl-sidebar-width: 20rem;
+
+    /* Accents (Shared) */
+    --gameface-cyan: #00DCFF;
+    --gameface-blue: #3E42B8;
+
+    /* --- DARK MODE PALETTE (Default) --- */
+    --gameface-bg-main: #0A0A0A;
+    --gameface-bg-content: #141414;
+    /* Deep Teal */
+    --gameface-bg-panel: #141414;
+    --gameface-border: #262626;
+    --gameface-text-head: #FFFFFF;
+    --gameface-text-body: #F4F4F4;
+    --gameface-text-meta: #8fa3a3;
+
+    /* Starlight Mappings (Dark) */
+    --sl-color-bg: var(--gameface-bg-main);
+    --sl-color-bg-nav: var(--gameface-bg-panel);
+    --sl-color-bg-sidebar: var(--gameface-bg-main);
+    --sl-color-white: var(--gameface-text-head);
+    --sl-color-text: var(--gameface-text-body);
+    --sl-color-text-accent: var(--gameface-cyan);
+
+    --sl-color-accent: var(--gameface-cyan);
+    --sl-color-accent-high: #99f3ff;
+    --sl-color-accent-low: #003640;
+
+    --sl-color-gray-1: #F4F4F4;
+    --sl-color-gray-2: #c1d1d1;
+    --sl-color-gray-3: var(--gameface-text-meta);
+    --sl-color-gray-4: #5f7575;
+    --sl-color-gray-5: var(--gameface-border);
+    --sl-color-gray-6: var(--gameface-bg-panel);
+
+    --sl-color-hairline: var(--gameface-border);
+    --overlay-backdrop: rgba(10, 10, 10, 0.95);
+    --before-after-line: rgba(255, 255, 255, 0.43);
+  }
+
+  main .sl-container {
+    max-width: none;
+  }
+
+  .content-panel {
+    padding: 1.5rem 1.5rem;
+  }
+
+  @media (min-width: 72rem) {
+    .content-panel {
+      padding: 1.5rem 2.5rem;
+    }
+  }
+
+  @media (min-width: 90rem) {
+    .content-panel {
+      padding: 1.5rem 3.5rem;
+    }
+  }
+
+  .right-sidebar {
+    width: fit-content;
+  }
+
+  /* ========================================= */
+  /* 2. LIGHT THEME OVERRIDES                  */
+  /* ========================================= */
+  [data-theme='light'] {
+    /* --- Gameface Light Palette --- */
+    /* Backgrounds: White (Main) and Light Grey 1 (Sidebars) */
+    --gameface-bg-main: #FFFFFF;
+    --gameface-bg-content: #FFFFFF;
+    --gameface-bg-panel: #F4F4F4;
+    --gameface-border: #E0E0E0;
+    /* Subtle border for light mode */
+
+    /* Text Colors */
+    --gameface-text-head: #0A0A0A;
+    /* Coherent Black */
+    --gameface-text-body: #333333;
+    /* Dark Grey 2 */
+    --gameface-text-meta: #666666;
+    /* Grey */
+
+    /* Starlight Mappings (Light) */
+    --sl-color-bg: var(--gameface-bg-main);
+    --sl-color-bg-nav: var(--gameface-bg-main);
+    /* Header blends with main */
+    --sl-color-bg-sidebar: var(--gameface-bg-panel);
+    /* Light Grey Sidebar */
+
+    /* Re-mapping 'White' var to Black because Starlight uses it for Headings */
+    --sl-color-white: var(--gameface-text-head);
+    --sl-color-text: var(--gameface-text-body);
+    --sl-color-text-accent: #009bb3;
+    /* Darker Cyan for text readability on white */
+
+    --sl-color-accent: var(--gameface-cyan);
+    --sl-color-accent-high: #008fa6;
+    --sl-color-accent-low: #e0faff;
+
+    /* Grays (Inverted for Light Mode) */
+    --sl-color-gray-1: #1a1a1a;
+    --sl-color-gray-2: #333333;
+    --sl-color-gray-3: var(--gameface-text-meta);
+    --sl-color-gray-4: #999999;
+    --sl-color-gray-5: var(--gameface-border);
+    --sl-color-gray-6: #F9F9F9;
+
+    --sl-color-hairline: var(--gameface-border);
+    --overlay-backdrop: rgba(255, 255, 255, 0.95);
+    --before-after-line: rgba(10, 10, 10, 0.43);
+  }
+
+  /* ========================================= */
+  /* 3. DEEP TEAL LOGIC (DARK MODE ONLY)       */
+  /* ========================================= */
+  /* Apply Deep Teal background ONLY in Dark Mode and NOT on Splash pages */
+  :root:not([data-theme='light']) body:not([data-template="splash"]) {
+    --sl-color-bg: var(--gameface-bg-content);
+    /* #0F2123 */
+    --sl-color-bg-sidebar: var(--gameface-bg-main);
+    /* Keep Sidebar Black */
+  }
+
+  /* ========================================= */
+  /* 4. GLOBAL RESET & TYPOGRAPHY              */
+  /* ========================================= */
+  /* Strictly sharp corners */
+  *,
+  *::before,
+  *::after {
+    border-radius: 0 !important;
+  }
+
+  body {
+    font-family: var(--sl-font-system);
+    color: var(--sl-color-text);
+  }
+
+  h1,
+  /* h2,
+  h3,
+  h4,
+  h5,
+  h6, */
+  .site-title {
+    font-family: var(--sl-font-heading);
+    text-transform: uppercase !important;
+    font-weight: 600 !important;
+    letter-spacing: 0.02em;
+    color: var(--sl-color-white);
+  }
+
+  /* Labels: Bold Caps, 0.2em spacing */
+  .sl-badge,
+  .kbd,
+  button,
+  .button {
+    font-family: 'Karla', sans-serif;
+    font-weight: 700;
+  }
+
+  .sl-link-button.primary {
+    font-weight: bold;
+    transition: filter 0.2s ease, border-color 0.2s ease;
+    border: 1px solid transparent;
+  }
+
+  .sl-link-button.primary:hover {
+    filter: brightness(1.2);
+  }
+
+  .sl-link-button.secondary {
+    transition: border-color 0.2s ease, color 0.2s ease;
+  }
+
+  .sl-link-button.secondary:hover {
+    border-color: var(--gameface-cyan);
+    color: var(--gameface-cyan)
+  }
+
+  .sl-link-button.minimal {
+    transition: color 0.2s ease;
+  }
+
+  .sl-link-button.minimal:hover {
+    color: var(--gameface-cyan)
+  }
+
+  /* ========================================= */
+  /* 5. COMPONENT STYLING                      */
+  /* ========================================= */
+
+  /* --- Header --- */
+  header.header {
+    background-color: var(--overlay-backdrop) !important;
+    border-bottom: 1px solid var(--sl-color-hairline) !important;
+    backdrop-filter: blur(10px);
+  }
+
+  /* --- Left Sidebar --- */
+  nav.sidebar {
+    background-color: var(--sl-color-bg-sidebar) !important;
+    border-right: 1px solid var(--sl-color-hairline);
+  }
+
+  .sidebar-content details summary {
+    flex-direction: row-reverse;
+    justify-content: flex-end;
+    padding: 0.2em 0.2em;
+  }
+
+  .sidebar-content details summary .group-label {
+    padding-left: 0.3em;
+  }
+
+  .sidebar-content details li {
+    border-inline-start: 1px solid var(--sl-color-gray-5);
+    padding-inline-start: var(--sl-sidebar-item-padding-inline);
+    position: relative;
+    margin-inline-start: calc(var(--sl-sidebar-item-padding-inline) + (0.5rem / 2));
+  }
+
+  .sidebar-content details li:hover {
+    color: var(--sl-color-white);
+  }
+
+  .sidebar-content details li:hover:not(:has(li:hover)) {
+    border-color: var(--sl-color-gray-1);
+  }
+
+  .sidebar-content details li:has(>a[aria-current=page]) {
+    background-color: var(--sl-color-gray-6) !important;
+  }
+
+  .sidebar-content details li:has(>a[aria-current=page])::before {
+    content: '';
+    position: absolute;
+    left: -1px;
+    height: 100%;
+    color: var(--sl-color-white);
+    border-left: 4px solid var(--gameface-cyan) !important;
+  }
+
+  .sidebar-content ul a {
+    color: var(--sl-color-gray-3);
+  }
+
+  /* Active Page Styling */
+  .sidebar-content ul a[aria-current="page"] {
+    color: var(--gameface-cyan) !important;
+    background-color: transparent !important;
+    font-weight: 700;
+  }
+
+  /* Fix for Light Mode Text on Active Sidebar */
+  [data-theme='light'] .sidebar-content ul a[aria-current="page"] {
+    color: #009bb3 !important;
+    /* Darker cyan for readability on light bg */
+  }
+
+  .sidebar-content ul a:hover:not([aria-current="page"]) {
+    color: var(--sl-color-white);
+  }
+
+  .right-sidebar a {
+    padding-inline-start: calc(1rem - 4px) !important;
+    border-left: 4px solid transparent;
+  }
+
+  .right-sidebar ul ul {
+    padding-inline-start: 1rem !important;
+  }
+
+  .right-sidebar a[aria-current="true"] {
+    color: var(--gameface-cyan) !important;
+    font-weight: 700;
+    border-left-color: var(--gameface-cyan) !important;
+    padding-inline-start: calc(1rem - 4px) !important;
+  }
+
+  /* Light mode override for TOC active text */
+  [data-theme='light'] .right-sidebar a[aria-current="true"] {
+    color: #009bb3 !important;
+  }
+
+  #starlight__on-this-page {
+    border-left: 4px solid var(--gameface-cyan) !important;
+    padding-left: calc(1rem - 4px);
+  }
+
+  .right-sidebar h2 {
+    letter-spacing: 0.15em !important;
+    color: var(--sl-color-white) !important;
+    margin-bottom: 1rem;
+  }
+
+  /* --- Cards & UI --- */
+  .card,
+  .sl-link-card {
+    background-color: var(--sl-color-bg-nav) !important;
+    /* Context aware */
+    border: 1px solid var(--sl-color-gray-5);
+    transition: border-color 0.2s;
+  }
+
+  .card:hover,
+  .card:focus,
+  .sl-link-card:hover,
+  .sl-link-card:focus {
+    border-color: var(--gameface-cyan);
+  }
+
+  /* Code Blocks */
+  .expressive-code .frame {
+    background-color: var(--gameface-bg-panel) !important;
+    /* Code is usually dark even in light mode for Gameface? */
+    border: 1px solid var(--sl-color-gray-5);
+  }
+
+  /* Override for Light mode if code blocks should be light (Optional, keeping dark per typical tech docs) */
+  [data-theme='light'] .expressive-code .frame {
+    background-color: #f0f0f0 !important;
+    border-color: #ccc;
+  }
+
+  /* Admonitions */
+  .starlight-aside--tip,
+  .starlight-aside--note {
+    border: 1px solid var(--sl-color-hairline) !important;
+    border-left: 4px solid var(--sl-color-asides-text-accent) !important;
+  }
+
+  .starlight-aside__title {
+    font-family: var(--sl-font-heading);
+    text-transform: uppercase;
+  }
+
+  /* --- Pagination Buttons --- */
+  /* Next: Cyan Background, Black Text */
+  .pagination-links a[rel="next"] {
+    border: none;
+    font-weight: 800;
+    text-transform: uppercase;
+  }
+
+  /* Prev: Ghost Button */
+  .pagination-links a {
+    transition: all 0.2s ease;
+  }
+
+  .pagination-links a[rel="prev"],
+  .pagination-links a[rel="next"] {
+    font-weight: 800;
+    background-color: transparent !important;
+    border: none;
+    color: var(--sl-color-gray-3) !important;
+    text-transform: uppercase;
+    box-shadow: none;
+  }
+
+  .pagination-links .link-title {
+    color: inherit !important;
+    font-size: var(--sl-text-xl);
+  }
+
+  .pagination-links a[rel="prev"]:hover,
+  .pagination-links a[rel="next"]:hover {
+    color: var(--sl-color-white) !important;
+  }
+
+  /* Light mode prev button needs dark border/text */
+  [data-theme='light'] .pagination-links a[rel="prev"],
+  [data-theme='light'] .pagination-links a[rel="next"] {
+    border-color: var(--gameface-text-head) !important;
+    color: var(--gameface-text-head) !important;
+  }
+
+  [data-theme='light'] .pagination-links a[rel="prev"]:hover,
+  [data-theme='light'] .pagination-links a[rel="next"]:hover {
+    color: var(--sl-color-gray-3) !important;
+  }
+
+  /* --- Theme Toggle --- */
+  starlight-theme-select {
+    border: 1px solid var(--sl-color-gray-5);
+  }
+
+  starlight-theme-select select {
+    opacity: 0;
+  }
+
+  starlight-theme-select:hover {
+    border-color: var(--gameface-cyan);
+  }
+
+  starlight-theme-select svg {
+    color: var(--gameface-cyan);
+  }
+
+  [data-theme='light'] starlight-theme-select svg {
+    color: #009bb3;
+    /* Darker cyan for visibility */
+  }
+
+  .starlight-sidebar-topics-dropdown-button-label,
+  .starlight-sidebar-topics-dropdown-label {
+    white-space: pre-line !important;
+  }
+
+  .starlight-sidebar-topics-dropdown-button-label {
+    margin-right: 0 !important;
+  }
+
+  starlight-menu-button button {
+    background-color: transparent;
+    color: var(--sl-color-gray-1);
+    box-shadow: none;
+  }
+
+  starlight-menu-button button:hover {
+    opacity: 0.66;
+  }
+
+  site-search button {
+    font-size: var(--sl-icon-size);
+  }
+
+  site-search button:hover {
+    opacity: 0.66;
+  }
+}

package/utils/changelogSideBar.ts

@@ -0,0 +1,105 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkMdx from 'remark-mdx';
+
+type Heading = { label: string; link: string, badge?: { text: string, variant: "note" | "danger" | "success" | "caution" | "tip" | "default" | undefined } };
+const headings: Heading[] = [];
+
+function parseHeadingWithBadge(node: any) {
+    const text = node.children
+        .filter((child: any) => child.type === 'text')
+        .map((child: any) => child.value)
+        .join('');
+
+    const badgeNode = node.children.find(
+        (child: any) =>
+            child.type === 'text' &&
+            child.value.includes(':badge[')
+    );
+
+    let badgeText = '';
+    if (badgeNode) {
+        const match = badgeNode.value.match(/:badge\[(.*?)\]/);
+        if (match) {
+            badgeText = match[1];
+        }
+    }
+
+    const badgeVariantNode = node.children.find(
+        (child: any) =>
+            child.type === 'mdxTextExpression' &&
+            child.value.includes('variant="')
+    );
+
+    let badgeVariant: "note" | "danger" | "success" | "caution" | "tip" | "default" | undefined;
+    if (badgeVariantNode) {
+        const match = badgeVariantNode.value.match(/variant="(.*?)"/);
+        if (match) {
+            badgeVariant = match[1];
+        }
+    }
+
+    let badge = null;
+    if (badgeText) {
+        badge = { text: badgeText, variant: badgeVariant };
+    }
+
+    return { text, badge };
+}
+
+function slugify(text: string) {
+    return text
+        .replace(/:badge\[.*?\]/g, '')
+        .trim()
+        .toLowerCase()
+        .replace(/\s+/g, '-')
+        .replace(/[^\w\-]+/g, '')
+}
+
+function walk(node: any) {
+    if (node.type === 'heading' && node.depth === 2) {
+        const { text, badge } = parseHeadingWithBadge(node);
+        const heading: Heading = {
+            label: text.replace(/:badge\[.*?\]/g, ''),
+            link: `/changelog/#${slugify(text)}`,
+        };
+
+        if (badge) {
+            heading.badge = {
+                text: badge.text,
+                variant: badge.variant
+            }
+        }
+
+        headings.push(heading);
+    }
+
+    if (node.children) {
+        for (const child of node.children) {
+            walk(child);
+        }
+    }
+}
+
+export default function generateChangelog(changelogPath: string) {
+    const filePath = path.resolve(changelogPath);
+    const file = fs.readFileSync(filePath, 'utf-8');
+
+    const { content } = matter(file);
+
+    const tree = unified()
+        .use(remarkParse)
+        .use(remarkMdx)
+        .parse(content);
+
+    walk(tree);
+    return {
+        label: 'Changelog',
+        items: [
+            ...headings
+        ]
+    }
+}