Run the docs locally

This documentation site lives in docs/ at the repository root and is built with VitePress. You can run it locally, build a static bundle, or deploy it to Vercel.

1. Install dependencies

cd docs
bun install

Only one runtime dependency is needed: vitepress. Bun installs it into docs/node_modules/.

2. Start the dev server

bun run dev

Output:

  vitepress v1.6.4

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

Open http://localhost:5173 — you should see the N2E Fleet Management User Guide landing page.

The dev server has hot reload:

• Edit any .md page in docs/ → the browser updates instantly.
• Edit .vitepress/config.ts → the sidebar / nav rebuilds and the page reloads.
• Drop a screenshot into docs/public/screenshots/ → it is served from /screenshots/... immediately.

Pick another port

If 5173 is in use, pass --port:

bun vitepress dev --port 5174

3. Build the static site

bun run build

VitePress emits the production bundle to docs/.vitepress/dist/. This is the directory you upload to any static host (Vercel, Netlify, S3, GitHub Pages, …).

The build also runs a dead-link check. If it complains, fix the broken link in the offending Markdown file and rebuild. http://localhost:* links are intentionally allowed via ignoreDeadLinks: 'localhostLinks' in the config.

4. Preview the production build

bun run preview

Serves docs/.vitepress/dist/ on a local port. Use this to sanity-check the build before pushing — especially after touching vitepress config.

Available scripts

bun run dev      # Dev server with HMR (default port 5173)
bun run build    # Static build → .vitepress/dist
bun run preview  # Serve the built site locally

These are all defined in docs/package.json.

Project layout

docs/
├── .vitepress/
│   ├── config.ts          # Site config: nav, sidebar, search, theme
│   ├── cache/             # Build cache (git-ignored)
│   └── dist/              # Build output (git-ignored)
├── guide/                 # End-user documentation
│   └── driver/            # Driver-specific pages
├── dev/                   # Developer documentation
├── public/
│   └── screenshots/       # Live screenshots used in the guides
├── index.md               # Landing page (hero + features)
├── package.json
├── bun.lock
└── vercel.json            # Vercel deploy config

Pages are plain Markdown — add a new file in the right folder and reference it from .vitepress/config.ts sidebar entries. URL paths follow the file path; e.g. docs/guide/driver/trips.md becomes /guide/driver/trips.

Deploying

The repo ships a working docs/vercel.json that points Vercel at the VitePress output directory:

{
  "buildCommand": "bun run build",
  "outputDirectory": ".vitepress/dist",
  "installCommand": "bun install",
  "framework": null,
  "cleanUrls": true,
  "trailingSlash": false
}

Steps:

1. Create a new Vercel project from the repo.
2. Set Root Directory to docs/.
3. Vercel detects vercel.json and uses the values above.
4. Push to main — Vercel builds and serves the static bundle on your domain (e.g. n2e-docs.daosolution.io).

For self-hosting, run bun run build and copy the .vitepress/dist/ folder to any static host or CDN.

Adding a new page

1. Create the Markdown file under docs/guide/<topic>.md or docs/dev/<topic>.md.
2. Add its title and frontmatter (optional — VitePress reads the first # heading by default).
3. Reference the file from the right sidebar block in .vitepress/config.ts:

{
  text: 'My new section',
  items: [
    { text: 'My new page', link: '/guide/my-new-page' },
  ],
}

4. The dev server picks up the new file immediately. Run bun run build once before committing to confirm no dead links.

Adding screenshots

1. Drop the PNG into docs/public/screenshots/<name>.png (or a subfolder).
2. Reference it from any Markdown page with ![alt](/screenshots/<name>.png).
3. The public directory is served at the site root, so the path always starts with /screenshots/.

When screenshots include emails or other sensitive data, mask them in the browser before capturing — see the existing flow in Run the frontend and the helper script attached to the screenshot capture workflow.

Troubleshooting

Symptom	Fix
Cannot find module 'vitepress'	Re-run bun install inside docs/.
Port 5173 is already in use	Stop the other instance or pass --port 5174.
Build fails with "dead link"	Open the offending file and correct the link, or add to ignoreDeadLinks in .vitepress/config.ts.
Sidebar item missing	Check .vitepress/config.ts — the file must be referenced in a sidebar block, not just exist on disk.
Theme toggle missing	The toggle is built into VitePress — confirm you haven't overridden head or appearance in the config.