@evgenest/vitepress-theme-contour 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 evgenest
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,95 @@
-# Temporary Holding Version
+# @evgenest/vitepress-theme-contour
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A theme for [VitePress](https://vitepress.dev) 2 that adds some variety to the stock look: a wider layout, framed code blocks and a few small tools for reading long code. It extends the default theme, so everything you already use in VitePress keeps working, including local search.
+
+> **Requires VitePress 2**, which is still in alpha. The theme styles some of VitePress's internal class names, so a new VitePress version can break parts of it. Keep your lockfile committed and look over your site after upgrading.
+
+## Features
+
+**Layout**
+- Left sidebar pinned to the edge of the window, with the active page on a filled background
+- Search box and page text aligned on one line
+- A wider text column, up to 1100 px
+- The "On this page" outline hugs the right edge and takes only the width its text needs
+- A site header that stays visible while scrolling on narrow screens
+
+**Code blocks**
+- Frame, higher-contrast plain text and a styled but visible scrollbar
+- Copy button that appears on hover and shows a green "Copied!" label
+- Line-wrap button: one click applies to every code block on the site and is remembered in the browser
+- Text never runs under the buttons: wrapped text flows around them, and an unwrapped first line fades out before them, then scrolls fully clear
+
+**Navigation**
+- Auto / Light / Dark switch in the header on wide screens
+- Previous and next links as cards with arrows
+- On narrow screens, the outline highlights the current section and closes after you pick an item
+- `sidebarTree()` builds a nested sidebar from your folders
+- Interface language: English or Russian
+
+## Install
+
+```sh
+bun add -d vitepress@next @evgenest/vitepress-theme-contour
+```
+
+npm, pnpm and yarn work too.
+
+## Set up
+
+`.vitepress/theme/index.ts`:
+
+```ts
+export { default } from '@evgenest/vitepress-theme-contour'
+```
+
+`.vitepress/config.ts`:
+
+```ts
+import { contourConfig, sidebarTree } from '@evgenest/vitepress-theme-contour/config'
+
+export default {
+  extends: contourConfig({ locale: 'en' }), // or 'ru'
+  title: 'My docs',
+  themeConfig: {
+    sidebar: sidebarTree(),
+  },
+}
+```
+
+## Sidebar
+
+`sidebarTree()` turns each folder into a nested group and each Markdown file into a link. All options are optional:
+
+```ts
+sidebarTree({
+  srcDir: 'docs',                    // same as srcDir in your config
+  exclude: ['drafts.md'],            // paths relative to srcDir
+  order: ['intro.md', 'guide'],      // listed first, the rest follow alphabetically
+  titles: { 'intro.md': 'Welcome' }, // overrides the name in the menu
+  rootLabel: 'Docs',                 // wraps the tree in one top-level group
+  collapsed: false,
+})
+```
+
+The menu name comes from `titles`, then frontmatter `title`, then the first `#` heading, then the file name.
+
+`exclude` only hides a page from the menu. To leave it off the site, also add it to `srcExclude`.
+
+A `README.md` in the root of `srcDir` links to `/`, so add `rewrites: { 'README.md': 'index.md' }` if you use one as your home page.
+
+## Your own `markdown.config`
+
+You can set `markdown.config` as usual: VitePress runs it together with the theme's own, so the wrap buttons stay.
+
+## Colors
+
+Colors are CSS variables. Override them in your own stylesheet, imported from `.vitepress/theme/index.ts`:
+
+```css
+:root { --vp-c-brand-1: #0f766e; }
+.dark { --vp-c-brand-1: #5eead4; }
+```
+
+## License
+
+MIT

package/config.d.ts

@@ -0,0 +1,19 @@
+import type { DefaultTheme, UserConfig } from 'vitepress'
+
+export type ContourLocale = 'en' | 'ru'
+
+export function contourConfig(options?: { locale?: ContourLocale }): UserConfig<DefaultTheme.Config>
+
+export function sidebarTree(options?: {
+  /** Folder with the Markdown files, the same as `srcDir` in your config. */
+  srcDir?: string
+  /** Paths relative to `srcDir` to leave out of the menu. */
+  exclude?: string[]
+  /** Menu names by path. Otherwise: frontmatter `title`, then the first `#` heading, then the file name. */
+  titles?: Record<string, string>
+  /** Paths in the order they should appear; everything else follows alphabetically. */
+  order?: string[]
+  /** Wraps the whole tree in one top-level group. */
+  rootLabel?: string
+  collapsed?: boolean
+}): DefaultTheme.SidebarItem[]

package/config.js

@@ -0,0 +1,146 @@
+import { readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+const PACKAGE = '@evgenest/vitepress-theme-contour'
+
+const LABELS = {
+  en: {
+    contour: { theme: 'Theme', auto: 'Auto', light: 'Light', dark: 'Dark', wrapOn: 'Wrap lines', wrapOff: 'Do not wrap lines' },
+    copy: 'Copy code',
+    copied: 'Copied!',
+    themeConfig: { docFooter: { prev: 'Previous', next: 'Next' } },
+  },
+  ru: {
+    contour: { theme: 'Тема', auto: 'Авто', light: 'Светлая', dark: 'Тёмная', wrapOn: 'Переносить строки', wrapOff: 'Не переносить строки' },
+    copy: 'Копировать',
+    copied: 'Скопировано!',
+    permalink: 'Ссылка на раздел',
+    themeConfig: {
+      search: {
+        provider: 'local',
+        options: {
+          translations: {
+            button: { buttonText: 'Поиск', buttonAriaLabel: 'Поиск' },
+            modal: {
+              noResultsText: 'Ничего не найдено по запросу',
+              displayDetails: 'Показать развёрнутые результаты',
+              resetButtonTitle: 'Очистить',
+              backButtonTitle: 'Закрыть',
+              footer: {
+                selectText: 'открыть',
+                selectKeyAriaLabel: 'Enter',
+                navigateText: 'выбрать',
+                navigateUpKeyAriaLabel: 'стрелка вверх',
+                navigateDownKeyAriaLabel: 'стрелка вниз',
+                closeText: 'закрыть',
+                closeKeyAriaLabel: 'Escape',
+              },
+            },
+          },
+        },
+      },
+      outline: { label: 'На этой странице' },
+      sidebarMenuLabel: 'Меню',
+      returnToTopLabel: 'Наверх',
+      darkModeSwitchLabel: 'Тема',
+      lightModeSwitchTitle: 'Включить светлую тему',
+      darkModeSwitchTitle: 'Включить тёмную тему',
+      skipToContentLabel: 'Перейти к содержимому',
+      langMenuLabel: 'Сменить язык',
+      navMenuLabel: 'Навигация',
+      mobileMenuLabel: 'Меню',
+      extraMenuLabel: 'Ещё',
+      notFound: {
+        title: 'СТРАНИЦА НЕ НАЙДЕНА',
+        quote: 'Такой страницы здесь нет. Вернитесь на главную или воспользуйтесь поиском.',
+        linkLabel: 'на главную',
+        linkText: 'На главную',
+      },
+      docFooter: { prev: 'Предыдущая', next: 'Следующая' },
+    },
+  },
+}
+
+// markdown-it plugin: adds the wrap button to every code block.
+function contourMarkdown(md, { locale = 'en' } = {}) {
+  const labels = LABELS[locale]
+  const fence = md.renderer.rules.fence
+  const label = labels.contour.wrapOn
+  md.renderer.rules.fence = (...args) =>
+    fence(...args).replace(
+      '<button',
+      `<button type="button" class="wrap" title="${label}" aria-label="${label}" aria-pressed="false"></button><button`,
+    )
+  if (labels.permalink) {
+    md.core.ruler.push('contour-permalink', (state) => {
+      for (const token of state.tokens) {
+        for (const child of token.children ?? []) {
+          if (child.type !== 'link_open') continue
+          const value = child.attrGet('aria-label')
+          if (value?.startsWith('Permalink to')) {
+            child.attrSet('aria-label', value.replace('Permalink to', labels.permalink))
+          }
+        }
+      }
+    })
+  }
+}
+
+/** Base config to pass to `extends`. */
+export function contourConfig({ locale = 'en' } = {}) {
+  const labels = LABELS[locale]
+  if (!labels) throw new Error(`${PACKAGE}: unknown locale "${locale}", use one of: ${Object.keys(LABELS).join(', ')}`)
+  return {
+    lang: locale,
+    // Applied before first paint so code blocks do not jump on load.
+    head: [
+      ['script', {}, "try{if(localStorage.getItem('code-wrap')==='1')document.documentElement.classList.add('code-wrap')}catch(e){}"],
+    ],
+    vite: { ssr: { noExternal: [PACKAGE] } },
+    markdown: {
+      codeCopyButton: { tooltipText: labels.copy, copiedText: labels.copied },
+      config: (md) => contourMarkdown(md, { locale }),
+    },
+    themeConfig: {
+      search: { provider: 'local' },
+      ...labels.themeConfig,
+      contour: labels.contour,
+    },
+  }
+}
+
+function pageTitle(file, fallback) {
+  const text = readFileSync(file, 'utf8')
+  const front = text.match(/^---\r?\n[\s\S]*?^title:\s*(.+)$[\s\S]*?^---/m)
+  const heading = text.match(/^# (.+)$/m)
+  return (front?.[1] ?? heading?.[1] ?? fallback).trim().replace(/^['"]|['"]$/g, '')
+}
+
+/** Builds a sidebar tree from the folders in `srcDir`. */
+export function sidebarTree({ srcDir = '.', exclude = [], titles = {}, order = [], rootLabel, collapsed = false } = {}) {
+  const isHome = (path) => path === 'README.md' || path === 'index.md'
+  const rank = (path) => {
+    const i = order.indexOf(path)
+    if (i !== -1) return i
+    return isHome(path) ? -1 : order.length
+  }
+  const walk = (rel) =>
+    readdirSync(join(srcDir, rel), { withFileTypes: true })
+      .filter((e) => !e.name.startsWith('.') && e.name !== 'node_modules' && e.name !== 'public')
+      .map((e) => ({ e, path: rel ? `${rel}/${e.name}` : e.name }))
+      .filter(({ e, path }) => e.isDirectory() || (e.name.endsWith('.md') && !exclude.includes(path)))
+      .sort((a, b) => rank(a.path) - rank(b.path) || a.path.localeCompare(b.path))
+      .map(({ e, path }) => {
+        if (e.isDirectory()) {
+          const items = walk(path)
+          return items.length ? { text: titles[path] ?? e.name, collapsed, items } : null
+        }
+        return {
+          text: titles[path] ?? pageTitle(join(srcDir, path), e.name),
+          link: isHome(path) ? '/' : `/${path.replace(/\.md$/, '')}`,
+        }
+      })
+      .filter(Boolean)
+  const items = walk('')
+  return rootLabel ? [{ text: rootLabel, collapsed, items }] : items
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@evgenest/vitepress-theme-contour",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "A VitePress 2 theme with a calmer layout, framed code blocks, a global line-wrap toggle and an auto/light/dark switch.",
+  "keywords": [
+    "vitepress",
+    "vitepress-theme",
+    "documentation",
+    "theme"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/evgenest/vitepress-theme-contour.git"
+  },
+  "homepage": "https://github.com/evgenest/vitepress-theme-contour#readme",
+  "bugs": {
+    "url": "https://github.com/evgenest/vitepress-theme-contour/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./theme/index.d.ts",
+      "default": "./theme/index.ts"
+    },
+    "./config": {
+      "types": "./config.d.ts",
+      "default": "./config.js"
+    }
+  },
+  "files": [
+    "theme",
+    "config.js",
+    "config.d.ts"
+  ],
+  "peerDependencies": {
+    "vitepress": "^2.0.0-alpha.21",
+    "vue": "^3.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/theme/ThemeSwitch.vue

@@ -0,0 +1,47 @@
+<script setup lang="ts">
+import { computed, nextTick, onMounted, ref } from 'vue'
+import { useData } from 'vitepress'
+
+const KEY = 'vitepress-theme-appearance'
+const { isDark, theme } = useData()
+const ui = computed(() => (theme.value as any).contour ?? { theme: 'Theme', auto: 'Auto', light: 'Light', dark: 'Dark' })
+const mode = ref('auto')
+
+onMounted(() => {
+  mode.value = localStorage.getItem(KEY) || 'auto'
+})
+
+async function change() {
+  const v = mode.value
+  const system = matchMedia('(prefers-color-scheme: dark)').matches
+  isDark.value = v === 'auto' ? system : v === 'dark'
+  // VitePress collapses a choice equal to the system theme into auto,
+  // so the explicit choice is written after its own write.
+  await nextTick()
+  localStorage.setItem(KEY, v)
+}
+</script>
+
+<template>
+  <label class="theme-switch">
+    <span class="sr-only">{{ ui.theme }}</span>
+    <select v-model="mode" @change="change" :aria-label="ui.theme">
+      <option value="auto">{{ ui.auto }}</option>
+      <option value="light">{{ ui.light }}</option>
+      <option value="dark">{{ ui.dark }}</option>
+    </select>
+  </label>
+</template>
+
+<style scoped>
+.theme-switch { display: none; align-items: center; margin-left: 16px; }
+@media (min-width: 1280px) { .theme-switch { display: flex; } }
+.sr-only { position: absolute; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); }
+select {
+  height: 32px; padding: 0 10px; font-size: 13px; cursor: pointer;
+  color: var(--vp-c-text-1); background: var(--vp-c-bg);
+  border: 1px solid var(--vp-c-border); border-radius: 6px;
+  appearance: auto;
+}
+select:hover { border-color: var(--vp-c-brand-1); }
+</style>

package/theme/custom.css

@@ -0,0 +1,267 @@
+/* Palette and framing; font and inline code stay as in VitePress. */
+:root {
+  --contour-header-bg: #f6f7f9;
+  --contour-on-accent: #ffffff;
+  --vp-c-bg: #ffffff;
+  --vp-c-bg-alt: #f6f7f9;
+  --vp-c-bg-soft: #f6f7f9;
+  --vp-c-text-1: #17181c;
+  --vp-c-text-2: #353841;
+  --vp-c-text-3: #6b6f7b;
+  --vp-c-divider: #e3e4e8;
+  --vp-c-gutter: #e3e4e8;
+  --vp-c-border: #c1c3c8;
+  --vp-c-brand-1: #3d50f5;
+  --vp-c-brand-2: #3344d6;
+  --vp-c-brand-3: #3d50f5;
+  --vp-c-brand-soft: rgba(61, 80, 245, 0.12);
+  --vp-code-color: #3451b2;
+  --vp-code-bg: rgba(142, 150, 170, 0.14);
+  --vp-code-block-bg: #f6f7f9;
+  --contour-code-text: #2b2d36;
+  --contour-scroll: #a9acb5;
+  --vp-sidebar-width: 300px;
+  --vp-nav-bg-color: #f6f7f9;
+  --vp-sidebar-bg-color: var(--vp-c-bg);
+  --contour-gutter: 36px;
+}
+.dark {
+  --contour-header-bg: #23262f;
+  --contour-on-accent: #17264f;
+  --vp-nav-bg-color: #23262f;
+  --vp-c-bg: #17181c;
+  --vp-c-bg-alt: #23262f;
+  --vp-c-bg-soft: #23262f;
+  --vp-c-bg-elv: #23262f;
+  --vp-c-text-1: #ffffff;
+  --vp-c-text-2: #c1c3c8;
+  --vp-c-text-3: #8b8e98;
+  --vp-c-divider: #353841;
+  --vp-c-gutter: #353841;
+  --vp-c-border: #4a4e5a;
+  --vp-c-brand-1: #b3c7ff;
+  --vp-c-brand-2: #9db5ff;
+  --vp-c-brand-3: #b3c7ff;
+  --vp-c-brand-soft: rgba(179, 199, 255, 0.14);
+  --vp-code-color: #a8b1ff;
+  --vp-code-bg: rgba(101, 117, 133, 0.16);
+  --vp-code-block-bg: #23262f;
+  --contour-code-text: #d6deeb;
+  --contour-scroll: #6a6e7b;
+  --vp-sidebar-bg-color: #23262f;
+}
+
+/* Full-width header. */
+.VPNavBar, .VPNavBar.has-sidebar, .VPNavBar:not(.home) {
+  background: var(--contour-header-bg) !important;
+  border-bottom: 1px solid var(--vp-c-divider);
+}
+.VPNavBar .divider { display: none; }
+.VPNavBar .content-body, .VPNavBar .title { background: transparent !important; backdrop-filter: none !important; }
+.VPNavBarTitle .title { color: var(--vp-c-brand-1); font-size: 22px; font-weight: 600; border: 0; }
+
+@media (min-width: 960px) {
+  /* Sidebar pinned to the left edge. */
+  .VPSidebar {
+    width: var(--vp-sidebar-width) !important;
+    padding: 80px 16px 48px !important;
+    background: var(--vp-sidebar-bg-color) !important;
+    border-right: 1px solid var(--vp-c-divider);
+  }
+  .VPSidebar .curtain { display: none; }
+  .VPContent.has-sidebar { padding-left: var(--vp-sidebar-width) !important; padding-right: 0 !important; }
+  .VPFooter { padding-left: var(--vp-sidebar-width) !important; }
+
+  .VPNavBar.has-sidebar .container { max-width: none !important; }
+  .VPNavBar.has-sidebar .wrapper { padding: 0 24px !important; }
+  .VPNavBar.has-sidebar .title { left: 0 !important; width: var(--vp-sidebar-width) !important; padding: 0 0 0 24px !important; position: absolute !important; }
+  .VPNavBar.has-sidebar .content { padding-left: calc(var(--vp-sidebar-width) - 24px) !important; padding-right: 0 !important; }
+  .VPNavBar .content-body { justify-content: flex-start !important; }
+
+  /* Search aligned with the page text. */
+  .VPNavBarSearch { flex-grow: 1; justify-content: flex-start; padding-left: var(--contour-gutter) !important; }
+  .VPNavBarSearchButton {
+    width: 352px; height: 40px; margin: 0; padding: 0 8px 0 12px; justify-content: flex-start;
+    background: var(--vp-c-bg) !important; border: 1px solid var(--vp-c-border); border-radius: 8px;
+  }
+  .VPNavBarSearchButton:hover { border-color: var(--vp-c-brand-1); }
+  .VPNavBarSearchButton .keys { margin-left: auto; }
+  .VPNavBarAppearance { display: none !important; }
+  .VPNavBarExtra { margin-left: auto; }
+
+  /* Text starts right after the sidebar. */
+  .VPDoc.has-sidebar, .VPDoc { padding: 40px 0 64px !important; }
+  .VPDoc .container { display: flex; justify-content: flex-start !important; max-width: none !important; margin: 0 !important; }
+  .VPDoc > .container > .content { flex: 1 1 0; min-width: 0; max-width: 1172px !important; padding: 0 var(--contour-gutter) !important; margin: 0 !important; order: 1; }
+  .VPDoc .content-container { max-width: none !important; margin: 0 !important; }
+
+  /* The right outline takes only the width its text needs. */
+  .VPDoc .aside { order: 2; flex: 0 0 auto; width: max-content; max-width: 360px !important; margin-left: auto; padding-left: 0 !important; padding-right: 24px; }
+  .VPDoc .aside-container { position: sticky; top: 104px; height: calc(100vh - 104px); padding-top: 0 !important; width: max-content !important; max-width: 100%; }
+  .VPDoc .aside-content { width: max-content !important; max-width: 100%; min-height: 0 !important; }
+  .VPDoc .aside-curtain { display: none; }
+}
+
+/* Sidebar: active item on a filled background. */
+.VPSidebarItem .indicator { display: none; }
+.VPSidebarItem.is-active > .item {
+  background: var(--vp-c-brand-1);
+  border-radius: 4px;
+}
+.VPSidebarItem.is-active > .item .link-text,
+.VPSidebarItem.is-active > .item .text { color: var(--contour-on-accent) !important; font-weight: 600; }
+.VPSidebarItem .item { padding-left: 8px; padding-right: 8px; }
+.VPSidebarItem.level-0 { padding-bottom: 0 !important; }
+.VPSidebarItem.level-0 > .item > .text { font-weight: 600; }
+.VPSidebarItem .items { border-left: 1px solid var(--vp-c-divider); margin-left: 8px; padding-left: 8px; }
+.VPSidebarItem .text { color: var(--vp-c-text-2) !important; font-size: 14px; }
+.VPSidebarItem .item:hover:not(:has(.is-active)) .text { color: var(--vp-c-brand-1) !important; }
+
+/* Right outline: VitePress rail, active item in the accent color. */
+.VPDocAsideOutline .outline-link.active { color: var(--vp-c-brand-1) !important; font-weight: 500; }
+/* Narrow screens: current section in color; clicks on item text reach the link so the list closes. */
+.VPLocalNavOutlineDropdown .outline-link.active { color: var(--vp-c-brand-1) !important; font-weight: 500; }
+.VPLocalNavOutlineDropdown .outline-link bdi { pointer-events: none; }
+.VPDocAsideOutline .outline-marker { background: var(--vp-c-brand-1); width: 2px; }
+
+/* Headings. */
+.vp-doc h1 { font-size: 36px; line-height: 1.2; color: var(--vp-c-text-1); letter-spacing: -0.02em; }
+.vp-doc h1:not(:first-of-type) { font-size: 24px; margin-top: 16px; color: var(--vp-c-text-2); font-weight: 500; letter-spacing: -0.01em; }
+.vp-doc h2 { color: var(--vp-c-text-1); }
+.vp-doc p, .vp-doc li, .vp-doc td { color: var(--vp-c-text-2); }
+
+/* Code blocks: frame, contrasting text, visible scrollbar. */
+.vp-doc div[class*='language-'] {
+  background: var(--vp-code-block-bg) !important;
+  border: 1px solid var(--vp-c-border);
+  border-radius: 6px !important;
+  margin-left: 0 !important;
+  margin-right: 0 !important;
+}
+.vp-doc div[class*='language-'] code { font-size: 14px; }
+.vp-doc div[class*='language-']:is(.language-, .language-txt, .language-text) .line span {
+  color: var(--contour-code-text) !important;
+}
+.vp-doc div[class*='language-'] > span.lang { display: none; }
+.vp-doc div[class*='language-'] pre { scrollbar-width: thin; scrollbar-color: var(--contour-scroll) transparent; }
+.vp-doc div[class*='language-'] pre::-webkit-scrollbar { height: 10px; }
+.vp-doc div[class*='language-'] pre::-webkit-scrollbar-thumb {
+  background: var(--contour-scroll); border-radius: 5px;
+  border: 2px solid var(--vp-code-block-bg);
+}
+.vp-doc div[class*='language-'] pre::-webkit-scrollbar-track { background: transparent; }
+:root {
+  --contour-icon-copy: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%2353565f' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Crect x='9' y='9' width='12' height='12' rx='2'/%3E%3Cpath d='M5 15H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v1'/%3E%3C/svg%3E");
+  --contour-icon-wrap: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%2353565f' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M3 6h18M3 12h15a3 3 0 0 1 0 6h-4M3 18h6'/%3E%3Cpath d='m16 16-2 2 2 2'/%3E%3C/svg%3E");
+  --contour-icon-wrap-on: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%233d50f5' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M3 6h18M3 12h15a3 3 0 0 1 0 6h-4M3 18h6'/%3E%3Cpath d='m16 16-2 2 2 2'/%3E%3C/svg%3E");
+  --contour-btn-hover: #dfe1e6;
+}
+.dark {
+  --contour-icon-copy: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23c1c3c8' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Crect x='9' y='9' width='12' height='12' rx='2'/%3E%3Cpath d='M5 15H4a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h10a1 1 0 0 1 1 1v1'/%3E%3C/svg%3E");
+  --contour-icon-wrap: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23c1c3c8' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M3 6h18M3 12h15a3 3 0 0 1 0 6h-4M3 18h6'/%3E%3Cpath d='m16 16-2 2 2 2'/%3E%3C/svg%3E");
+  --contour-icon-wrap-on: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%23b3c7ff' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M3 6h18M3 12h15a3 3 0 0 1 0 6h-4M3 18h6'/%3E%3Cpath d='m16 16-2 2 2 2'/%3E%3C/svg%3E");
+  --contour-btn-hover: #3a3e4a;
+}
+
+/* Code block buttons appear on hover. */
+.vp-doc div[class*='language-'] > button.copy,
+.vp-doc div[class*='language-'] > button.wrap {
+  position: absolute; z-index: 3; top: 8px; width: 32px; height: 32px;
+  border: 0 !important; border-radius: 4px; cursor: pointer;
+  background-color: var(--vp-code-block-bg) !important;
+  background-position: 50%; background-size: 18px; background-repeat: no-repeat;
+  opacity: 0; transition: opacity 0.2s, background-color 0.2s;
+}
+.vp-doc div[class*='language-'] > button.copy { right: 44px; inset-inline-end: 44px; background-image: var(--contour-icon-copy) !important; }
+.vp-doc div[class*='language-'] > button.wrap { right: 8px; background-image: var(--contour-icon-wrap); }
+.vp-doc div[class*='language-']:hover > button.copy,
+.vp-doc div[class*='language-']:hover > button.wrap,
+.vp-doc div[class*='language-'] > button:focus-visible { opacity: 0.8; }
+.vp-doc div[class*='language-'] > button.copy:hover,
+.vp-doc div[class*='language-'] > button.wrap:hover {
+  opacity: 1; background-color: var(--contour-btn-hover) !important;
+}
+@media (hover: none) {
+  .vp-doc div[class*='language-'] > button.copy,
+  .vp-doc div[class*='language-'] > button.wrap { opacity: 0.8; }
+}
+
+/* Line wrapping on. */
+:root.code-wrap .vp-doc div[class*='language-'] > button.wrap { background-image: var(--contour-icon-wrap-on); opacity: 1; }
+:root.code-wrap .vp-doc div[class*='language-'] pre { overflow-x: hidden; }
+:root.code-wrap .vp-doc div[class*='language-'] code { display: block; width: 100%; min-width: 0; white-space: pre-wrap; padding-right: 24px; }
+:root.code-wrap .vp-doc div[class*='language-'] .line { white-space: pre-wrap; overflow-wrap: anywhere; }
+
+/* Green copied label with an arrow to the button. */
+.vp-doc div[class*='language-'] > button.copy.copied,
+.vp-doc div[class*='language-'] > button.copy:hover.copied {
+  opacity: 1; border-radius: 4px !important; z-index: 5;
+  background-color: var(--contour-btn-hover) !important;
+  background-image: var(--contour-icon-copy) !important;
+}
+.vp-doc div[class*='language-'] > button.copy.copied::before,
+.vp-doc div[class*='language-'] > button.copy:hover.copied::before {
+  position: absolute; top: 50%; right: calc(100% + 8px); left: auto;
+  transform: translateY(-50%);
+  display: block; width: max-content; height: auto; padding: 2px 12px;
+  border: 0; border-radius: 4px;
+  font-size: 14px; font-weight: 400; line-height: 24px;
+  color: #fff; background: #078662;
+  content: attr(data-copied);
+}
+.vp-doc div[class*='language-'] > button.copy.copied::after,
+.vp-doc div[class*='language-'] > button.copy:hover.copied::after {
+  content: ''; position: absolute; top: 50%; right: calc(100% + 3px);
+  transform: translateY(-50%);
+  border: solid transparent; border-width: 5px 0 5px 5px;
+  border-left-color: #078662;
+}
+
+/* Footer navigation: cards with arrows. */
+.VPDocFooter .pager-link {
+  position: relative; display: block; height: 100%; padding: 16px 16px 16px 52px;
+  border: 1px solid var(--vp-c-border); border-radius: 8px;
+}
+.VPDocFooter .pager-link.next { padding: 16px 52px 16px 16px; text-align: right; }
+.VPDocFooter .pager-link:hover { border-color: var(--vp-c-brand-1); }
+.VPDocFooter .pager-link::before {
+  content: ''; position: absolute; top: 50%; left: 16px; width: 24px; height: 24px;
+  transform: translateY(-50%); background: var(--vp-c-text-2);
+  -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M19 12H5M11 6l-6 6 6 6'/%3E%3C/svg%3E") center / contain no-repeat;
+  mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M19 12H5M11 6l-6 6 6 6'/%3E%3C/svg%3E") center / contain no-repeat;
+}
+.VPDocFooter .pager-link.next::before { left: auto; right: 16px; transform: translateY(-50%) scaleX(-1); }
+.VPDocFooter .pager-link .desc { display: block; font-size: 14px; line-height: 20px; color: var(--vp-c-text-2); }
+.VPDocFooter .pager-link .title { display: block; margin-top: 2px; font-size: 20px; line-height: 28px; font-weight: 500; color: var(--vp-c-text-1); }
+
+@media (min-width: 1280px) { .VPNavBarExtra { display: none !important; } }
+
+/* Narrow screens: header and local nav stay while scrolling. */
+@media (max-width: 959.98px) {
+  .VPNav { position: sticky !important; top: 0; }
+  .VPLocalNav { top: var(--vp-nav-height) !important; }
+  .VPDoc .vp-doc :is(h1, h2, h3, h4, h5, h6) { scroll-margin-top: calc(var(--vp-nav-height) + 56px); }
+  .VPLocalNavOutlineDropdown .items { max-height: calc(100dvh - var(--vp-nav-height) - 72px) !important; }
+}
+
+/* Wrapped first row flows around the buttons. */
+:root.code-wrap .vp-doc div[class*='language-'] code::before {
+  content: ''; float: right; width: 60px; height: 22px;
+}
+
+/* No wrapping: the first line fades out before the buttons. */
+:root:not(.code-wrap) .vp-doc div[class*='language-']::before {
+  content: ''; position: absolute; z-index: 2; top: 0; right: 0;
+  width: 132px; height: 44px; pointer-events: none;
+  border-top-right-radius: 6px;
+  background: linear-gradient(to right, transparent, var(--vp-code-block-bg) 48px);
+  opacity: 0; transition: opacity 0.2s;
+}
+:root:not(.code-wrap) .vp-doc div[class*='language-']:hover::before,
+:root:not(.code-wrap) .vp-doc div[class*='language-']:focus-within::before { opacity: 1; }
+@media (hover: none) {
+  :root:not(.code-wrap) .vp-doc div[class*='language-']::before { opacity: 1; }
+}
+
+/* Room on the right so a fully scrolled first line clears the fade. */
+:root:not(.code-wrap) .vp-doc div[class*='language-'] .line:first-child { padding-right: 116px; }

package/theme/index.d.ts

@@ -0,0 +1,3 @@
+import type { Theme } from 'vitepress'
+declare const theme: Theme
+export default theme

package/theme/index.ts

@@ -0,0 +1,72 @@
+import { h, onMounted } from 'vue'
+import { inBrowser, onContentUpdated, useData } from 'vitepress'
+import DefaultTheme from 'vitepress/theme'
+import ThemeSwitch from './ThemeSwitch.vue'
+import './custom.css'
+
+const WRAP_KEY = 'code-wrap'
+let wrapLabels = { on: 'Wrap lines', off: 'Do not wrap lines' }
+
+// Keep every wrap button in step with the global state.
+function syncWrapButtons() {
+  const on = document.documentElement.classList.contains(WRAP_KEY)
+  const label = on ? wrapLabels.off : wrapLabels.on
+  document.querySelectorAll("div[class*='language-'] > button.wrap").forEach((button) => {
+    button.setAttribute('aria-pressed', String(on))
+    button.setAttribute('aria-label', label)
+    button.setAttribute('title', label)
+  })
+}
+
+// The stock mobile outline has no current-section highlight.
+function markCurrentHeading() {
+  const links = [...document.querySelectorAll<HTMLAnchorElement>('.VPLocalNavOutlineDropdown .outline-link')]
+  const heading = (link: HTMLAnchorElement) => document.getElementById(decodeURIComponent(link.hash.slice(1)))
+  const atBottom = window.scrollY + window.innerHeight >= document.documentElement.scrollHeight - 1
+  let current: HTMLAnchorElement | undefined = atBottom ? links.at(-1) : undefined
+  if (!current) {
+    for (const link of links) {
+      const el = heading(link)
+      if (!el) continue
+      const margin = Number.parseFloat(getComputedStyle(el).scrollMarginTop) || 0
+      if (el.getBoundingClientRect().top > margin + 4) break
+      current = link
+    }
+  }
+  links.forEach((link) => link.classList.toggle('active', link === current))
+  current?.scrollIntoView({ block: 'nearest' })
+}
+
+export default {
+  extends: DefaultTheme,
+  Layout: () =>
+    h(DefaultTheme.Layout, null, {
+      'nav-bar-content-after': () => h(ThemeSwitch),
+    }),
+  setup() {
+    const { theme } = useData()
+    const ui = (theme.value as any).contour
+    if (ui) wrapLabels = { on: ui.wrapOn, off: ui.wrapOff }
+    onMounted(syncWrapButtons)
+    onContentUpdated(syncWrapButtons)
+  },
+  enhanceApp() {
+    if (!inBrowser) return
+    window.addEventListener('click', (e) => {
+      const button = e.target as HTMLElement
+      if (button.closest?.('.VPLocalNavOutlineDropdown > button')) {
+        requestAnimationFrame(markCurrentHeading)
+        return
+      }
+      if (!button.matches?.("div[class*='language-'] > button.wrap")) return
+      // Blocks above change height: keep the pressed button where it is on screen.
+      const top = button.getBoundingClientRect().top
+      const on = document.documentElement.classList.toggle(WRAP_KEY)
+      try {
+        localStorage.setItem(WRAP_KEY, on ? '1' : '0')
+      } catch {}
+      syncWrapButtons()
+      window.scrollBy({ top: button.getBoundingClientRect().top - top, behavior: 'instant' })
+    })
+  },
+}