docs: rebuild documentation site on Fumadocs (bilingual zh/en)

.github/workflows/deploy-docs.yaml

@@ -4,7 +4,7 @@ on:
   push:
     branches:
       - main
-      - feat/docs
+      - feat/new-docs
     paths:
       - 'docs/**'
       - '.github/workflows/deploy-docs.yaml'
@@ -16,35 +16,60 @@ permissions:
   pages: write
   id-token: write
 
+# Allow one concurrent deployment; cancel in-progress runs.
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
 jobs:
-  deploy:
+  build:
     runs-on: ubuntu-latest
-    environment:
-      name: github-pages
+    defaults:
+      run:
+        working-directory: docs
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
         with:
-          python-version: '3.12'
+          node-version: 22
 
-      - name: Install dependencies
+      # pnpm via corepack (bundled with Node) — avoids third-party setup actions
+      # that are blocked by the org's allowed-actions policy.
+      - name: Enable pnpm
         run: |
-          cd docs
-          pip install -r requirements.txt
+          corepack enable
+          corepack prepare pnpm@10.16.1 --activate
 
-      - name: Build MkDocs site
-        run: |
-          cd docs
-          mkdocs build
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build static site (Fumadocs)
+        run: pnpm build:static
+        env:
+          # GitHub Pages project site is served from /<repo>. Without this base
+          # path, assets and routes 404 under the sub-path. (The pitfall.)
+          NEXT_PUBLIC_BASE_PATH: /${{ github.event.repository.name }}
+          # Optional: external Ask-AI endpoint (e.g. a VeFaaS function).
+          NEXT_PUBLIC_AI_CHAT_URL: ${{ vars.AI_CHAT_URL }}
 
       - name: Upload artifact for GitHub Pages
         uses: actions/upload-pages-artifact@v3
         with:
-          path: docs/site/
+          path: docs/out
 
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    # The github-pages environment restricts deployments to the default branch.
+    # Branches/PRs run the build job above to validate; deploy happens on main.
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
       - name: Deploy to GitHub Pages
         id: deploy
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4

.gitignore

@@ -201,4 +201,6 @@ cython_debug/
 *.mp3
 *.pcm
 
-.trae
+.trae
+.claude
+.agents

.gitleaks.toml

@@ -73,4 +73,10 @@ description = "Empty environment variables with KEY pattern"
 regex = '''os\.environ\[".*?KEY"\]\s*=\s*".+"'''
 
 [allowlist]
-paths = ["requirements.txt", "tests", "veadk/realtime/client.py", "veadk/realtime/live.py"]
+paths = ["requirements.txt", "tests", "veadk/realtime/client.py", "veadk/realtime/live.py"]
+# False positives: the docs search config references the @orama/tokenizers
+# package and its createTokenizer() helper. The word "tokenizer" trips
+# token-transformer-id-pattern, but these are library identifiers, not secrets.
+regexes = [
+  '''tokenizer''',
+]

docs/.gitignore

@@ -1,172 +1,32 @@
-# Byte-compiled / optimized / DLL files
-__pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
-
-# Distribution / packaging
-.Python
-develop-eggs/
-dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
-*.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
-
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
-.pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/#use-with-ide
-.pdm.toml
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
-
-# mkdocs documentation
-/site
-
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-.idea/
-
-# vscode
-.vscode/
-# Windsurf
-.windsurf
-
-# python package
-uv.lock
-
-# VitePress related files (security concern - keep Markdown docs in repo)
-docs/package.json
-docs/package-lock.json
-docs/node_modules/
+# deps
+/node_modules
+
+# generated content
+.source
+
+# test & build
+/coverage
+/.next/
+/out/
+/build
+*.tsbuildinfo
+
+# misc
+.DS_Store
+*.pem
+/.pnp
+.pnp.js
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# others
+.env*.local
+.vercel
+next-env.d.ts
+
+# The repo root .gitignore is a Python template that ignores `lib/` and
+# `build/`. This is a JS project — re-include our source dirs.
+!/lib
+!/lib/**
+!/build

docs/README.md

@@ -0,0 +1,47 @@
+# veadk-docs-scaffold
+
+This is a Next.js application generated with
+[Create Fumadocs](https://github.com/fuma-nama/fumadocs).
+
+It is a Next.js app with [Static Export](https://nextjs.org/docs/app/guides/static-exports) configured.
+
+Run development server:
+
+```bash
+npm run dev
+# or
+pnpm dev
+# or
+yarn dev
+```
+
+Open http://localhost:3000 with your browser to see the result.
+
+## Explore
+
+In the project, you can see:
+
+- `lib/source.ts`: Code for content source adapter, [`loader()`](https://fumadocs.dev/docs/headless/source-api) provides the interface to access your content.
+- `lib/layout.shared.tsx`: Shared options for layouts, optional but preferred to keep.
+
+| Route                     | Description                                            |
+| ------------------------- | ------------------------------------------------------ |
+| `app/(home)`              | The route group for your landing page and other pages. |
+| `app/docs`                | The documentation layout and pages.                    |
+| `app/api/search/route.ts` | The Route Handler for search.                          |
+
+### Fumadocs MDX
+
+A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
+
+Read the [Introduction](https://fumadocs.dev/docs/mdx) for further details.
+
+## Learn More
+
+To learn more about Next.js and Fumadocs, take a look at the following
+resources:
+
+- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js
+  features and API.
+- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+- [Fumadocs](https://fumadocs.dev) - learn about Fumadocs

docs/app/[lang]/(home)/layout.tsx

@@ -0,0 +1,14 @@
+import type { ReactNode } from 'react';
+import { HomeLayout } from 'fumadocs-ui/layouts/home';
+import { baseOptions } from '@/lib/layout.shared';
+
+export default async function Layout({
+  params,
+  children,
+}: {
+  params: Promise<{ lang: string }>;
+  children: ReactNode;
+}) {
+  const { lang } = await params;
+  return <HomeLayout {...baseOptions(lang)}>{children}</HomeLayout>;
+}