chore(docs): add deployment workflow and polish navbar search and footer

.github/workflows/docs.yml

@@ -0,0 +1,84 @@
+name: Docs
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'src/**'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - 'wrangler.toml'
+      - '.github/workflows/docs.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'src/**'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - 'wrangler.toml'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  deployments: write
+
+concurrency:
+  group: scopeview-docs-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  deploy:
+    name: ${{ github.event_name == 'pull_request' && 'Deploy preview' || 'Deploy production' }}
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: ${{ github.event_name == 'pull_request' && 'preview' || 'production' }}
+      url: ${{ steps.publish.outputs.url }}
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version-file: .node-version
+          package-manager-cache: false
+      - uses: pnpm/action-setup@0977fd99725f1db4007ccb2928dbb4e90d06cc86 # v6
+        with:
+          cache: true
+      - run: pnpm install --frozen-lockfile
+      - name: Publish documentation
+        id: publish
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+        run: |
+          set -euo pipefail
+          if [[ "${GITHUB_EVENT_NAME}" == "pull_request" ]]; then
+            output="$(pnpm exec wrangler versions upload \
+              --preview-alias "pr-${{ github.event.pull_request.number }}" \
+              --message "GitHub PR #${{ github.event.pull_request.number }} at ${GITHUB_SHA}" 2>&1 | tee /dev/stderr)"
+            version_url="$(grep 'Version Preview URL:' <<< "${output}" | grep -Eo 'https://[^[:space:]]+\.workers\.dev' | tail -n 1 || true)"
+            alias_url="$(grep 'Version Preview Alias URL:' <<< "${output}" | grep -Eo 'https://[^[:space:]]+\.workers\.dev' | tail -n 1 || true)"
+            preview_url="${alias_url:-${version_url}}"
+            if [[ -n "${preview_url}" ]]; then
+              echo "url=${preview_url}" >> "${GITHUB_OUTPUT}"
+            fi
+            {
+              echo "### Documentation Preview"
+              echo ""
+              echo "| Target | URL |"
+              echo "| :--- | :--- |"
+              if [[ -n "${alias_url}" ]]; then
+                echo "| PR #${{ github.event.pull_request.number }} (branch alias) | ${alias_url} |"
+              fi
+              if [[ -n "${version_url}" ]]; then
+                echo "| Commit \`${GITHUB_SHA::7}\` (immutable) | ${version_url} |"
+              fi
+            } >> "${GITHUB_STEP_SUMMARY}"
+          else
+            pnpm exec wrangler deploy
+            echo "url=https://scopeview.scopedb.io" >> "${GITHUB_OUTPUT}"
+          fi

docs/.vitepress/config.ts

@@ -3,19 +3,26 @@ import { defineConfig } from 'vitepress';
 import { nav, sidebar } from './navigation.js';
 
 const repository = 'https://github.com/scopedb/scopeview';
+const siteUrl = 'https://scopeview.scopedb.io';
+const siteTitle = 'ScopeView';
+const siteDescription =
+  'Small Canvas charts with exact source readings and no runtime dependencies.';
+const ogImageUrl = `${siteUrl}/og-image.png`;
+const ogImageAlt =
+  'ScopeView — Time-series charts with exact readings. Small Canvas charts for metrics, logs, and sparklines.';
 const base = process.env.SCOPEVIEW_DOCS_BASE || '/';
 if (!base.startsWith('/') || !base.endsWith('/')) {
   throw new Error('SCOPEVIEW_DOCS_BASE must start and end with a slash, for example /scopeview/.');
 }
 
 export default defineConfig({
-  title: 'ScopeView',
-  description: 'Small Canvas charts with exact source readings and no runtime dependencies.',
+  title: siteTitle,
+  description: siteDescription,
   lang: 'en-US',
   base,
   srcExclude: ['README.md'],
   sitemap: {
-    hostname: 'https://scopeview.scopedb.io'
+    hostname: siteUrl
   },
   outDir: fileURLToPath(new URL('../../.local/docs-site', import.meta.url)),
   cacheDir: fileURLToPath(new URL('../../.local/docs-cache', import.meta.url)),
@@ -33,20 +40,64 @@ export default defineConfig({
         href: `${base}icon.svg`
       }
     ],
-    ['meta', { property: 'og:site_name', content: 'ScopeView' }],
-    ['meta', { property: 'og:type', content: 'website' }]
+    ['meta', { property: 'og:site_name', content: siteTitle }],
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:locale', content: 'en_US' }],
+    ['meta', { property: 'og:image', content: ogImageUrl }],
+    ['meta', { property: 'og:image:type', content: 'image/png' }],
+    ['meta', { property: 'og:image:width', content: '1200' }],
+    ['meta', { property: 'og:image:height', content: '630' }],
+    ['meta', { property: 'og:image:alt', content: ogImageAlt }],
+    ['meta', { name: 'twitter:card', content: 'summary_large_image' }],
+    ['meta', { name: 'twitter:image', content: ogImageUrl }],
+    ['meta', { name: 'twitter:image:alt', content: ogImageAlt }]
   ],
+  transformPageData(pageData) {
+    const pageTitle =
+      !pageData.title || pageData.title === siteTitle
+        ? siteTitle
+        : `${pageData.title} | ${siteTitle}`;
+    const pageDescription = pageData.description || siteDescription;
+    const cleanPath = pageData.relativePath.replace(/(?:^|\/)index\.md$/, '').replace(/\.md$/, '');
+    const pageUrl = cleanPath ? `${siteUrl}/${cleanPath}` : `${siteUrl}/`;
+
+    pageData.frontmatter.head ??= [];
+    pageData.frontmatter.head.push(
+      ['meta', { property: 'og:title', content: pageTitle }],
+      ['meta', { property: 'og:description', content: pageDescription }],
+      ['meta', { property: 'og:url', content: pageUrl }],
+      ['meta', { name: 'twitter:title', content: pageTitle }],
+      ['meta', { name: 'twitter:description', content: pageDescription }]
+    );
+  },
   themeConfig: {
-    logo: '/icon.svg',
-    siteTitle: 'ScopeView',
+    logo: {
+      light: '/scopedb-symbol-black.svg',
+      dark: '/scopedb-symbol-white.svg',
+      alt: ''
+    },
+    siteTitle,
     nav,
     socialLinks: [{ icon: 'github', link: repository }],
-    search: { provider: 'local' },
+    search: {
+      provider: 'local',
+      options: {
+        translations: {
+          button: {
+            buttonText: 'Search docs...',
+            buttonAriaLabel: 'Search docs'
+          }
+        }
+      }
+    },
     outline: { level: [2, 3], label: 'On this page' },
     sidebar,
     docFooter: { prev: 'Previous page', next: 'Next page' },
     editLink: { pattern: `${repository}/edit/main/docs/:path`, text: 'Edit this page on GitHub' },
-    footer: { message: 'Apache-2.0 · ScopeView' }
+    footer: {
+      message: `Released under the <a href="${repository}/blob/main/LICENSE">Apache-2.0 License</a>.`,
+      copyright: `© 2024–${new Date().getFullYear()} <a href="https://www.scopedb.io">ScopeDB</a>. All rights reserved.`
+    }
   },
   markdown: {
     config(md) {

docs/.vitepress/theme/custom.css

@@ -0,0 +1,104 @@
+/* Align navbar brand mark and wordmark proportions with the ScopeDB Brand Kit. */
+.VPNavBarTitle .logo {
+  width: 22px;
+  height: 22px;
+  margin-right: 7px;
+}
+
+.VPNavBarTitle .title {
+  font-size: 18px;
+  font-weight: 680;
+  letter-spacing: -0.03em;
+}
+
+/* Refine navbar search trigger so it reads as a balanced search input rather than a cramped pill. */
+@media (min-width: 768px) {
+  .VPNavBarSearch.search {
+    justify-content: flex-end;
+    padding-left: 24px;
+    padding-right: 20px;
+  }
+
+  #local-search .DocSearch-Button {
+    width: 240px;
+    height: 36px;
+    padding: 0 10px 0 12px;
+    justify-content: space-between;
+    border: 1px solid var(--vp-c-divider);
+    border-radius: 8px;
+    background-color: var(--vp-c-bg-alt);
+    transition:
+      border-color 0.2s,
+      background-color 0.2s,
+      box-shadow 0.2s;
+  }
+
+  #local-search .DocSearch-Button:hover {
+    border-color: var(--vp-c-brand-1);
+    background-color: var(--vp-c-bg);
+  }
+
+  #local-search .DocSearch-Button-Container {
+    gap: 8px;
+  }
+
+  #local-search .DocSearch-Search-Icon {
+    width: 15px;
+    height: 15px;
+    color: var(--vp-c-text-2);
+  }
+
+  #local-search .DocSearch-Button-Placeholder {
+    font-size: 13px;
+    font-weight: 400;
+    color: var(--vp-c-text-2);
+  }
+
+  #local-search .DocSearch-Button-Keys {
+    min-width: auto;
+    padding: 2px 6px;
+    border: 1px solid var(--vp-c-divider);
+    border-radius: 5px;
+    background-color: var(--vp-c-bg);
+    gap: 1px;
+  }
+
+  #local-search .DocSearch-Button-Key {
+    border: 0 !important;
+    background: transparent !important;
+    padding: 0 !important;
+    margin: 0 !important;
+    min-width: auto !important;
+    height: 16px !important;
+    line-height: 16px !important;
+    font-size: 11px !important;
+    color: var(--vp-c-text-3) !important;
+  }
+}
+
+.VPFooter {
+  padding: 28px 24px !important;
+}
+
+.VPFooter .message,
+.VPFooter .copyright {
+  font-size: 13px;
+  line-height: 22px;
+  color: var(--vp-c-text-2);
+}
+
+.VPFooter a {
+  color: var(--vp-c-text-1);
+  font-weight: 500;
+  text-decoration: underline;
+  text-decoration-color: var(--vp-c-divider);
+  text-underline-offset: 3px;
+  transition:
+    color 0.2s,
+    text-decoration-color 0.2s;
+}
+
+.VPFooter a:hover {
+  color: var(--vp-c-brand-1);
+  text-decoration-color: var(--vp-c-brand-1);
+}

docs/.vitepress/theme/index.ts

@@ -4,6 +4,7 @@ import { ref } from 'vue';
 import ChartDemo from './ChartDemo.vue';
 import HeadlessDemo from './HeadlessDemo.vue';
 import { demoRouteVersion } from './demo-route.js';
+import './custom.css';
 
 export default {
   extends: DefaultTheme,

package.json

@@ -148,6 +148,7 @@
     "docs:dev": "vitepress dev docs --host 127.0.0.1",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs --host 127.0.0.1",
+    "docs:deploy": "wrangler deploy",
     "test:node": "node --test tests/node/*.test.mjs",
     "test:package": "node tests/package/run.mjs",
     "build:cli": "pnpm build && node scripts/distribution.mjs",
@@ -165,7 +166,8 @@
     "vitepress": "1.6.4",
     "vitest": "4.1.10",
     "vue": "3.5.43",
-    "vue-tsc": "3.3.12"
+    "vue-tsc": "3.3.12",
+    "wrangler": "4.154.0"
   },
   "engines": {
     "node": ">=24"