Skip to Content
DeploymentPublishing these docs

Publishing these docs

This site is Nextra 4  (Next.js App Router + MDX) with the nextra-theme-docs theme. The source is in docs/ in the repo.

Layout

docs/
├── package.json          # next, nextra, nextra-theme-docs, react
├── next.config.mjs        # withNextra() - MDX loader, copy-code, search
├── mdx-components.js       # global MDX components (Callout, Tabs, Steps, …)
├── app/
│   ├── layout.jsx          # <Layout> shell: navbar, footer, Inter font, theme
│   ├── globals.css          # Inter + card / mermaid polish on top of the theme
│   └── [[...mdxPath]]/page.jsx   # the catch-all that renders content/*.mdx
└── content/              # the docs - one folder per sidebar section
    ├── _meta.js            # top-level nav order
    ├── index.mdx
    ├── manifesto/  architecture/  internals/  deployment/  roadmap/  reference/
    │     └── _meta.js        # per-section nav order + titles

content/**/_meta.js files control the sidebar order and labels. A new page is just a new .mdx file plus an entry in its folder’s _meta.js.

Run it locally

Node 18+ (the repo was set up with Node 24, run portably from C:\Users\Sourajit\tools\node).

cd docs
npm install
npm run dev          # http://localhost:3000  (Turbopack, hot reload)

Turbopack, not webpack

dev and build both pass --turbopack. The webpack path hit filesystem-cache thrashing on this Windows setup; Turbopack is what Nextra 4 recommends anyway.

Build

npm run build        # .next/  - a Node server build
npm run start        # serve the production build on :3000

For a fully static deploy, uncomment output: 'export' in next.config.mjs:

export default withNextra({
  reactStrictMode: true,
  output: 'export',          // ← writes ./out with plain HTML
  images: { unoptimized: true },
})

then npm run build produces out/ - plain static files, host anywhere.

Put it on the web

With output: 'export', a workflow - .github/workflows/docs.yml:

name: Docs
on:
  push:
    branches: [main]
    paths: ['docs/**']
permissions:
  pages: write
  id-token: write
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22, cache: npm, cache-dependency-path: docs/package-lock.json }
      - run: npm ci
        working-directory: docs
      - run: npm run build
        working-directory: docs
      - uses: actions/upload-pages-artifact@v3
        with: { path: docs/out }
  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment: { name: github-pages, url: '${{ steps.d.outputs.page_url }}' }
    steps:
      - id: d
        uses: actions/deploy-pages@v4

Then Settings → Pages → Source: GitHub Actions. For a project-page path (/Viora/) set basePath in next.config.mjs.

Before going public

  • Set metadataBase in app/layout.jsx to the real domain (canonical URLs, OpenGraph).
  • Decide whether docsRepositoryBase / the edit link should point at a public branch.
  • Swap the gradient-square logo in app/layout.jsx for a real mark if you want one.
  • Search (Pagefind, built into the theme) indexes at build time - it works after npm run build, not in dev.
R8, minification & obfuscationOverview