Nefoxx Docs

Appearance

Contributing to these Docs ​

This portal is the single source of truth. Keep it cheap to extend and always in sync.

Where things live ​

documentations/portal/
  package.json            ← isolated; vitepress + mermaid (dev-only, never imported by the app)
  docs/
    .vitepress/config.mjs ← nav + sidebar (edit when you add a page)
    .vitepress/theme/     ← brand colors
    <section>/*.md        ← hand-authored pages
    reference/*.md        ← AUTO-GENERATED — do not edit by hand
    backend/edge-functions/index.md ← AUTO-GENERATED

Add a page (hand-authored) ​

  1. Create the .md under the right section (overview/ architecture/ features/ backend/ integrations/ auth/ guides/).
  2. For a feature, copy features/_template; for an EF, copy backend/edge-functions/_template.
  3. Add a sidebar entry in .vitepress/config.mjs.
  4. Keep it link-rich: reference real files by path and cross-link the generated indexes so a reader can trace UI → route → edge function → table.
  5. Prefer Mermaid diagrams (```mermaid) over prose for flows.

Never hand-edit generated files ​

reference/edge-functions.md, reference/routes.md, reference/database-tables.md, and backend/edge-functions/index.md are emitted by tools/generate-docs.js. They carry an AUTO-GENERATED banner. Edit the generator, not the output.

Re-generate (the sync contract) ​

Run npm run docs:gen whenever you:

  • add/rename/remove an edge function,
  • change route configuration,
  • add a migration that creates a table.

Suggested PR checklist item: "Ran npm run docs:gen; updated any affected hand-authored doc pages."

Run locally ​

bash
npm --prefix documentations/portal install   # one-time
npm run docs:gen
npm run docs:dev      # http://localhost:5173 by default
npm run docs:build    # static HTML → docs/.vitepress/dist

Production exclusion — do not break it ​

The portal must never ship to production. Two rules keep that true:

  • Never put portal files in the app's public/ directory.
  • Never import portal files from src/.

The app's vite build only bundles src/, index.html, and public/* into dist/. The portal lives outside all three and has its own separate build output (git-ignored). Don't add it to the app build.

Style ​

  • Concise and link-first; summarize and link the existing .md specs rather than copying them.
  • One concept per page; use tables for reference data.
  • Match the no-comments, no-fluff tone of the codebase.