initial commit

Author: kryptonianson

README.md

@@ -12,7 +12,7 @@ It documents BinaryNoir's open-source VitePress plugins, Vite plugins and comman
 | [`@binarynoir/vitepress-auto-navbar`](https://github.com/binarynoir/vitepress-auto-navbar)             | Builds the top navbar from the folder tree                 |
 | [`@binarynoir/vitepress-markdown-tags`](https://github.com/binarynoir/vitepress-markdown-tags)         | Status badges and tagged-page lists                        |
 | [`@binarynoir/vitepress-reading-time-tag`](https://github.com/binarynoir/vitepress-reading-time-tag)   | `[[readingTime]]` tip blocks                               |
-| [`markdown-it-glossary`](https://github.com/binarynoir/markdown-it-glossary)                           | Hover definitions from `docs/glossary.md`                  |
+| [`markdown-it-glossary`](https://github.com/binarynoir/markdown-it-glossary)                           | Hover definitions from `docs/reference/glossary.md`        |
 | [`@binarynoir/vite-plugin-optimize-images`](https://github.com/binarynoir/vite-plugin-optimize-images) | Re-compresses images in the build output                   |
 | [`@binarynoir/vite-plugin-image-fallback`](https://github.com/binarynoir/vite-plugin-image-fallback)   | Placeholder for missing images (one is missing on purpose) |
 

assets/detective-only-black.svg

@@ -2,6 +2,5 @@
 plugins
 apps
 guide
+reference
 ...
-glossary.md
-tagged-pages.md

assets/detective-only.svg

@@ -24,8 +24,19 @@ export default defineConfig({
   sitemap: { hostname: SITE_URL },
 
   head: [
-    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }],
-    ['meta', { name: 'theme-color', content: '#7a5add' }],
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/favicon.svg' }],
+    // Above-the-fold display font, fetched early to avoid a flash of fallback text.
+    [
+      'link',
+      {
+        rel: 'preload',
+        href: '/fonts/film-noir.woff2',
+        as: 'font',
+        type: 'font/woff2',
+        crossorigin: '',
+      },
+    ],
+    ['meta', { name: 'theme-color', content: '#111111' }],
     ['meta', { property: 'og:type', content: 'website' }],
     ['meta', { property: 'og:title', content: 'BinaryNoir' }],
     [
@@ -39,7 +50,7 @@ export default defineConfig({
   ],
 
   themeConfig: {
-    logo: '/logo.svg',
+    logo: { light: '/logo-light.svg', dark: '/logo-dark.svg', alt: 'BinaryNoir' },
 
     // @binarynoir/vitepress-auto-navbar: top nav built from the folder tree.
     // `.nav` files set order and titles; `.inherit` borrows titles from `.sidebar`.
@@ -72,9 +83,9 @@ export default defineConfig({
   markdown: {
     theme: { light: 'github-light', dark: 'github-dark' },
     config(md) {
-      // markdown-it-glossary: hover definitions from docs/glossary.md on every page.
+      // markdown-it-glossary: hover definitions from docs/reference/glossary.md on every page.
       // A page opts out with `glossary: false` in its frontmatter.
-      md.use(glossaryAbbr, { file: path.join(docsRoot, 'glossary.md') });
+      md.use(glossaryAbbr, { file: path.join(docsRoot, 'reference/glossary.md') });
       // @binarynoir/vitepress-reading-time-tag: [[readingTime]] becomes a tip block.
       md.use(readingTimeTag);
       // @binarynoir/vitepress-markdown-tags: ((tag|Done|green)) becomes a badge.

assets/full-logo.svg

@@ -1,17 +1,49 @@
+/* ---- Logo typefaces -------------------------------------------------------
+   Film Noir  : display. Wordmark, hero title and page titles (the big, rare text).
+   Rockwell   : slab serif for section headings and card titles.
+   Body text, code and navigation stay on the system sans so documentation reads fast.
+   Font files live in docs/public/fonts. */
+
+@font-face {
+  font-family: 'Film Noir';
+  src: url('/fonts/film-noir.woff2') format('woff2');
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'Rockwell';
+  src: url('/fonts/rockwell.woff2') format('woff2');
+  font-display: swap;
+}
+
 :root {
-  --vp-c-brand-1: #7a5add;
-  --vp-c-brand-2: #8d70e6;
-  --vp-c-brand-3: #6a49c9;
-  --vp-c-brand-soft: rgba(122, 90, 221, 0.14);
+  --bn-font-display: 'Film Noir', 'Impact', 'Arial Narrow', sans-serif;
+  --bn-font-slab: 'Rockwell', 'Rockwell Nova', 'Roboto Slab', 'Georgia', serif;
+}
+
+:root {
+  /* Noir palette, taken from the logo: black, white and one mid grey. */
+  --vp-c-brand-1: #1f1f1f;
+  --vp-c-brand-2: #3a3a3a;
+  --vp-c-brand-3: #111111;
+  --vp-c-brand-soft: rgba(17, 17, 17, 0.08);
 
   --vp-home-hero-name-color: transparent;
-  --vp-home-hero-name-background: linear-gradient(120deg, #7a5add 30%, #3aa6c9);
+  --vp-home-hero-name-background: linear-gradient(120deg, #111111 30%, #8a8a8a);
 }
 
 .dark {
-  --vp-c-brand-1: #a58cf0;
-  --vp-c-brand-2: #9577e8;
-  --vp-c-brand-3: #7a5add;
+  --vp-c-brand-1: #f0f0f0;
+  --vp-c-brand-2: #d4d4d4;
+  --vp-c-brand-3: #e5e5e5;
+  --vp-c-brand-soft: rgba(240, 240, 240, 0.14);
+
+  /* Brand buttons are light in dark mode, so their text must be dark. */
+  --vp-button-brand-text: #111111;
+  --vp-button-brand-hover-text: #111111;
+  --vp-button-brand-active-text: #111111;
+
+  --vp-home-hero-name-background: linear-gradient(120deg, #ffffff 30%, #8a8a8a);
 }
 
 /* Tooltips from markdown-it-glossary render as plain <abbr title>. Make them discoverable. */
@@ -24,3 +56,205 @@ abbr[title] {
 .vp-doc img {
   border-radius: 8px;
 }
+
+/* ---- Noir identity -------------------------------------------------------
+   Hard edges, strong contrast and one grey, to match the logo. */
+
+:root {
+  --vp-font-family-base:
+    'Inter', ui-sans-serif, system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue',
+    sans-serif;
+  --bn-line: rgba(17, 17, 17, 0.16);
+  --bn-line-strong: #111111;
+  --bn-radius: 2px;
+}
+
+.dark {
+  --bn-line: rgba(240, 240, 240, 0.18);
+  --bn-line-strong: #f0f0f0;
+}
+
+/* Wordmark and titles: Film Noir. */
+.VPNavBarTitle .title,
+.VPHero .name,
+.vp-doc h1 {
+  font-family: var(--bn-font-display);
+  font-weight: 400;
+  letter-spacing: 0.06em;
+  text-transform: uppercase;
+}
+
+.VPHero .name {
+  font-size: clamp(48px, 7vw, 72px);
+  /* Film Noir is tall; a roomy line box keeps the gradient text from clipping. */
+  line-height: 1.3;
+  padding-block: 4px;
+  letter-spacing: 0.08em;
+}
+
+.vp-doc h1 {
+  letter-spacing: 0.05em;
+}
+
+/* Tag badges inside headings keep the body font so they stay legible. */
+.vp-doc h1 .md-tag,
+.vp-doc h2 .md-tag {
+  font-family: var(--vp-font-family-base);
+  letter-spacing: 0;
+  text-transform: none;
+}
+
+/* Section headings and card titles: Rockwell. */
+.vp-doc h2,
+.vp-doc h3,
+.vp-doc h4,
+.VPHero .text,
+.VPFeature .title {
+  font-family: var(--bn-font-slab);
+  font-weight: 400;
+}
+
+.VPHero .text {
+  letter-spacing: -0.01em;
+}
+
+.VPNavBarTitle .logo {
+  height: 28px;
+}
+
+/* Hero: the full logo is portrait, so cap its height and drop the colored glow. */
+.VPHero .image-bg {
+  display: none;
+}
+
+.VPHero .image-src {
+  position: static;
+  transform: none;
+  max-height: 360px;
+  max-width: 100%;
+  width: auto;
+  margin-inline: auto;
+  border-radius: 0;
+}
+
+.VPHero .image {
+  margin: 0 0 24px;
+}
+
+@media (min-width: 640px) {
+  .VPHero .image {
+    margin: 0 0 24px;
+  }
+}
+
+@media (min-width: 960px) {
+  .VPHero .image {
+    margin: 0;
+  }
+}
+
+.VPHero .image-container {
+  display: flex;
+  justify-content: center;
+  height: auto;
+  /* VitePress pulls the image up with negative margins on small screens, which
+     slid the logo under the navbar and over the title. */
+  margin: 0;
+  padding-block: 24px;
+}
+
+@media (min-width: 960px) {
+  .VPHero .image-container {
+    width: auto;
+    min-width: 320px;
+  }
+}
+
+.VPHero .tagline {
+  max-width: 34rem;
+}
+
+/* Buttons: square, to match the logo's frame. */
+.VPButton.VPButton {
+  border-radius: var(--bn-radius);
+  font-weight: 600;
+}
+
+.VPButton.VPButton.alt {
+  border-color: var(--bn-line-strong);
+}
+
+/* Feature cards: outlined panels with a boxed icon, no soft fill. */
+.VPFeatures .VPFeature {
+  background: transparent;
+  border: 1px solid var(--bn-line);
+  border-radius: var(--bn-radius);
+  transition:
+    border-color 0.15s,
+    transform 0.15s;
+}
+
+.VPFeatures .VPFeature:hover {
+  border-color: var(--bn-line-strong);
+  transform: translateY(-2px);
+}
+
+.VPFeatures .VPFeature .icon {
+  background: transparent;
+  border: 1px solid var(--bn-line-strong);
+  border-radius: var(--bn-radius);
+  width: 52px;
+  height: 52px;
+}
+
+.VPFeatures .VPFeature .icon img {
+  width: 28px;
+  height: 28px;
+}
+
+.VPFeatures .VPFeature .link-text-value {
+  font-weight: 600;
+}
+
+/* Content: a scanline rule under each H2, echoing the dashes behind the detective. */
+.vp-doc h2 {
+  border-top: 0;
+  padding-top: 0;
+  margin-top: 56px;
+}
+
+.vp-doc h2::after {
+  content: '';
+  display: block;
+  height: 4px;
+  margin-top: 10px;
+  background: repeating-linear-gradient(90deg, var(--bn-line-strong) 0 24px, transparent 24px 30px);
+  opacity: 0.55;
+  width: 120px;
+}
+
+.vp-doc table,
+.vp-doc div[class*='language-'] {
+  border-radius: var(--bn-radius);
+}
+
+.vp-doc th {
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  font-size: 13px;
+}
+
+/* Keep keyboard focus obvious. */
+:focus-visible {
+  outline: 2px solid var(--bn-line-strong);
+  outline-offset: 2px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .VPFeature {
+    transition: none;
+  }
+  .VPFeatures .VPFeature:hover {
+    transform: none;
+  }
+}

docs/.nav

@@ -7,6 +7,6 @@ tagged:
 
 # Apps roadmap
 
-Every `Done` and `Planned` tag used on the app pages, collected automatically. This page has no list of its own: it is a [tagged page](/plugins/markdown-tags#tagged-pages) scoped to the `apps/` folder, so it stays current as the app pages change.
+Every `Done` and `Planned` tag used on the app pages, collected automatically. This page has no list of its own: it is a [tagged page](/plugins/markdown-tags/vitepress#tagged-pages) scoped to the `apps/` folder, so it stays current as the app pages change.
 
 <!-- tagged-pages -->

docs/.vitepress/config.mts

@@ -14,14 +14,13 @@ This site is plain VitePress 2 plus seven plugins. There is no hand-written navi
 docs/
   .nav                  top navbar order
   index.md              home page
-  glossary.md           terms for hover tooltips
-  tagged-pages.md       generated list of every tag
   plugins/              developer docs for each plugin
     .sidebar            order and titles for this section
   apps/                 user docs for the CLI apps
   guide/                this section
+  reference/            glossary terms and the generated list of every tag
   assets/               images imported by pages
-  public/               files served as-is (logo)
+  public/               files served as-is (logos, favicon, icons)
   .vitepress/
     config.mts          the one config file
     theme/              registers tag badges, brand colors
@@ -33,7 +32,7 @@ docs/
 | ------------------------------- | --------------------------------------------- | ------------------------------------- |
 | Top navbar                      | [Auto Navbar](/plugins/auto-navbar)           | `themeConfig.nav` in `config.mts`     |
 | Left sidebar                    | [Auto Sidebar](/plugins/auto-sidebar)         | `themeConfig.sidebar` in `config.mts` |
-| Status badges                   | [Markdown Tags](/plugins/markdown-tags)       | `markdown.config`, plus the theme     |
+| Status badges                   | [Markdown Tags](/plugins/markdown-tags/)      | `markdown.config`, plus the theme     |
 | "Reading time" box              | [Reading Time Tag](/plugins/reading-time-tag) | `markdown.config`                     |
 | Dotted-underline hovers         | [Glossary Tooltips](/plugins/glossary)        | `markdown.config`                     |
 | Smaller images                  | [Optimize Images](/plugins/optimize-images)   | `vite.plugins`                        |