docs: v2 docs & landing

.github/workflows/deploy-docs-v2.yaml

@@ -0,0 +1,71 @@
+name: Deploy docs-v2 (staging)
+
+on:
+  push:
+    branches: [enscribe/v2-docs]
+    paths:
+      - 'docs-v2/**'
+      - '.github/workflows/deploy-docs-v2.yaml'
+  workflow_dispatch:
+
+concurrency:
+  group: deploy-docs-v2
+  cancel-in-progress: true
+
+env:
+  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+
+jobs:
+  deploy:
+    name: Build and deploy to Vercel
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs-v2
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          persist-credentials: false
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version: 22
+
+      - uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+        with:
+          bun-version: latest
+
+      - name: Install Vercel CLI
+        run: bun install -g vercel@latest
+
+      - name: Pull Vercel environment
+        run: vercel pull --yes --environment=production --token="$VERCEL_TOKEN"
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+
+      - name: Build with Vercel
+        run: vercel build --prod --token="$VERCEL_TOKEN"
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+
+      - name: Deploy to Vercel (production)
+        id: deploy
+        shell: bash
+        run: |
+          set -euo pipefail
+          url=$(vercel deploy --prebuilt --prod --token="$VERCEL_TOKEN")
+          echo "url=$url" >> "$GITHUB_OUTPUT"
+        env:
+          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
+
+      - name: Write summary
+        shell: bash
+        run: |
+          set -euo pipefail
+          {
+            echo "## Staging deployment"
+            echo ""
+            echo "- Commit deploy URL: ${{ steps.deploy.outputs.url }}"
+            echo "- Stable staging URL: https://anchor-docs-staging.vercel.app/docs/"
+          } >> "$GITHUB_STEP_SUMMARY"

.gitignore

@@ -25,3 +25,5 @@ docker-target
 test-keypair.json
 tsconfig.tsbuildinfo
 .vscode
+*.stackdump
+CODEX_NOTES.md

docs-v2/.gitattributes

@@ -0,0 +1 @@
+*.mdx linguist-vendored

docs-v2/.gitignore

@@ -0,0 +1,14 @@
+dist/
+.astro/
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+.env
+.env.production
+.DS_Store
+.idea/
+teaser.pptx
+~$teaser.pptx
+.vercel

docs-v2/README.md

@@ -0,0 +1,13 @@
+<div align="center">
+
+## astro-erudocs
+
+</div>
+
+astro-erudocs is an opinionated, unstyled documentation framework built with [Astro](https://astro.build/), [Tailwind](https://tailwindcss.com/), and [shadcn/ui](https://ui.shadcn.com/). It is a sister project to [astro-erudite](https://github.com/jktrn/astro-erudite), inheriting its design system and technical-content tooling (Expressive Code, KaTeX, callouts, OKLCh tokens, view transitions) and re-shaping them around docs-native primitives: hierarchical sidebar, static search, prev/next navigation, and MDX components for steps, tabs, file trees, and cards.
+
+> [!WARNING] This repository is in active early development. The public API and file layout will change.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

docs-v2/astro.config.ts

@@ -0,0 +1,152 @@
+import { defineConfig } from 'astro/config'
+
+import mdx from '@astrojs/mdx'
+import react from '@astrojs/react'
+import sitemap from '@astrojs/sitemap'
+import pagefind from 'astro-pagefind'
+
+import { rehypeHeadingIds } from '@astrojs/markdown-remark'
+import rehypeAutolinkHeadings from 'rehype-autolink-headings'
+import rehypeExpressiveCode from 'rehype-expressive-code'
+import rehypeExternalLinks from 'rehype-external-links'
+import rehypeKatex from 'rehype-katex'
+import rehypeShiki from '@shikijs/rehype'
+import remarkEmoji from 'remark-emoji'
+import remarkMath from 'remark-math'
+
+import { rehypeInlineShellCmd } from './src/lib/rehype-inline-shell-cmd'
+import { rehypeInlinePathIcon } from './src/lib/rehype-inline-path-icon'
+import { rehypeWrapTables } from './src/lib/rehype-wrap-tables'
+import { ecOptions } from './src/lib/ec-config'
+import { latte, mocha } from './src/lib/shiki-themes'
+import { resolveSiteUrl } from './src/lib/site-url'
+
+import tailwindcss from '@tailwindcss/vite'
+import { extname, isAbsolute, relative, resolve } from 'node:path'
+import { readFile } from 'node:fs/promises'
+
+type DevMiddleware = (
+  req: { url?: string },
+  res: { setHeader(name: string, value: string): void; end(data: Uint8Array): void },
+  next: () => void,
+) => void | Promise<void>
+
+type DevServer = {
+  middlewares: {
+    use(path: string, handler: DevMiddleware): void
+  }
+}
+
+const DOCS_BASE = '/docs'
+const PAGEFIND_DIST_DIR = resolve(process.cwd(), 'dist', 'docs', 'pagefind')
+
+function pagefindDevServer() {
+  const mime: Record<string, string> = {
+    js: 'application/javascript',
+    mjs: 'application/javascript',
+    css: 'text/css',
+    json: 'application/json',
+    wasm: 'application/wasm',
+  }
+
+  return {
+    name: 'pagefind-dev-server',
+    enforce: 'pre' as const,
+    apply: 'serve' as const,
+    configureServer(server: DevServer) {
+      server.middlewares.use('/pagefind', async (req, res, next) => {
+        const filePath = resolvePagefindAsset(req.url ?? '/')
+        if (!filePath) return next()
+
+        try {
+          const data = await readFile(filePath)
+          const ext = extname(filePath).slice(1)
+          if (mime[ext]) res.setHeader('Content-Type', mime[ext])
+          res.end(data)
+        } catch {
+          next()
+        }
+      })
+    },
+  }
+}
+
+function resolvePagefindAsset(url: string): string | null {
+  let pathname: string
+  try {
+    pathname = decodeURIComponent(url.split('?')[0] ?? '/')
+  } catch {
+    return null
+  }
+
+  if (!pathname || pathname === '/') return null
+
+  const filePath = resolve(PAGEFIND_DIST_DIR, `.${pathname}`)
+  const relativePath = relative(PAGEFIND_DIST_DIR, filePath)
+
+  if (relativePath.startsWith('..') || isAbsolute(relativePath)) return null
+
+  return filePath
+}
+
+export default defineConfig({
+  site: resolveSiteUrl(),
+  base: DOCS_BASE,
+  trailingSlash: 'always',
+  outDir: './dist/docs',
+  integrations: [mdx(), react(), sitemap(), pagefind()],
+  vite: {
+    plugins: [tailwindcss(), pagefindDevServer()],
+  },
+  server: {
+    port: 4321,
+    host: true,
+  },
+  devToolbar: {
+    enabled: false,
+  },
+  markdown: {
+    syntaxHighlight: false,
+    rehypePlugins: [
+      [
+        rehypeExternalLinks,
+        {
+          target: '_blank',
+          rel: ['nofollow', 'noreferrer', 'noopener'],
+        },
+      ],
+      rehypeWrapTables,
+      rehypeKatex,
+      [rehypeExpressiveCode, { themes: [latte, mocha], ...ecOptions }],
+      [
+        rehypeShiki,
+        {
+          themes: { light: latte, dark: mocha },
+          inline: 'tailing-curly-colon',
+        },
+      ],
+      rehypeInlineShellCmd,
+      rehypeInlinePathIcon,
+      rehypeHeadingIds,
+      [
+        rehypeAutolinkHeadings,
+        {
+          behavior: 'append',
+          properties: {
+            className: ['heading-anchor'],
+            'aria-label': 'Link to section',
+            tabindex: -1,
+            'data-pagefind-ignore': '',
+          },
+          content: {
+            type: 'text',
+            value: '#',
+          },
+          test: (node: { tagName: string }) =>
+            ['h2', 'h3', 'h4', 'h5', 'h6'].includes(node.tagName),
+        },
+      ],
+    ],
+    remarkPlugins: [remarkMath, remarkEmoji],
+  },
+})