Voltimax Platform

Appearance

VitePress Configuration ​

Documentation is built with VitePress, a static site generator optimized for technical documentation.

Configuration File ​

Main configuration: docs/.vitepress/config.mts

This file defines:

  • Site metadata (title, description)
  • Theme configuration
  • Sidebar navigation
  • Build settings
  • Markdown extensions

Adding New Pages ​

1. Create the Markdown File ​

bash
# Example: Add an Azure deployment guide
docs/guide/deployment/azure.md

2. Write the Content ​

Use frontmatter for page metadata:

markdown
---
title: Azure Deployment
description: Deploy the platform to Azure


# Deploy to Azure

This guide shows how to deploy the platform to Azure...

3. Update the Sidebar ​

Edit the appropriate sidebar file in docs/.vitepress/sidebar/:

Example: guide.ts

typescript
export default [
  {
    text: 'Deployment',
    collapsed: true,
    items: [
      { text: 'Azure Deployment', link: '/guide/deployment/azure' },
      { text: 'Local Development', link: '/guide/deployment/local' }
    ]
  }
]

4. Test Locally ​

bash
cd docs
npm run docs:dev
# Visit http://localhost:5173

Each documentation section has its own sidebar configuration:

SectionSidebar FileMapped Path
User Guidesidebar/guide.ts/guide/
Integrationsidebar/integration.ts/integration/
Developersidebar/developer.ts/developer/
Referencesidebar/reference.ts/reference/

When adding or reorganising sidebar entries, follow these principles:

PrincipleRule
Journey orderingSections appear in the order a new reader encounters them: learn the system, build artifacts, understand cross-cutting concerns, contribute. Within a section: overview → concepts → details → tooling.
Dependency directionIf section B assumes knowledge from section A, A must appear first.
Cognitive proximityItems that answer the same kind of question sit together. Use inline comments (// Protocols, // Tooling, …) to label each cluster.
Consistent entry pointsEvery group with more than two items starts with an Overview page.
Max depth ≤ 3No page should require more than two clicks from the sidebar root.
Group size 2–8A single child is pointless nesting; 10+ children needs splitting.

Promote a topic to its own top-level section when it has an independent entry point, cuts across multiple deliverables, introduces its own vocabulary, has 3+ pages, and maps to a codebase boundary. Otherwise keep it as a sub-group.

Basic sidebar configuration:

typescript
export default [
  {
    text: 'Section Name',
    collapsed: true,  // Can be expanded/collapsed
    items: [
      { text: 'Page Title', link: '/path/to/page' },
      {
        text: 'Subsection',
        collapsed: true,
        items: [
          { text: 'Nested Page', link: '/path/to/nested' }
        ]
      }
    ]
  }
]

Sidebars are mapped to paths in config.mts:

typescript
export default defineConfig({
  themeConfig: {
    sidebar: {
      '/guide/': guide,
      '/integration/': integration,
      '/developer/': developer,
      '/reference/': reference
    }
  }
})

Top navigation is configured in config.mts:

typescript
export default defineConfig({
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' },
      { text: 'Integration', link: '/integration/' },
      { text: 'Developer', link: '/developer/' },
      { text: 'Reference', link: '/reference/' }
    ]
  }
})

Markdown Extensions ​

VitePress supports enhanced Markdown:

Frontmatter ​

markdown
---
title: Page Title
description: Page description for SEO
layout: doc
---

Code Groups ​

markdown
::: code-group
```bash [npm]
npm run docs:dev
\```

```bash [yarn]
yarn docs:dev
\```
:::

For callouts, links, diagrams, and other formatting conventions, see the Writing Guidelines.

Building Documentation ​

Local Development ​

Start development server with hot reload:

bash
cd docs
npm run docs:dev

Features:

  • Hot module replacement
  • Live preview at http://localhost:5173
  • Automatic page refresh on file changes

Production Build ​

Build static site for deployment:

bash
cd docs
npm run docs:build

Output: docs/.vitepress/dist/

Preview Production Build ​

Test the production build locally:

bash
cd docs
npm run docs:preview

This serves the built site from dist/ to verify the production build.

Deployment ​

The documentation is automatically deployed when:

  • Changes are pushed to the main branch
  • A pull request is merged
  • A release is created

Deployment targets:

  • Azure Static Web Apps
  • GitHub Pages (optional)
  • Custom hosting (configurable)

Advanced Configuration ​

Custom Theme ​

Extend the default theme in .vitepress/theme/index.ts:

typescript
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default {
  ...DefaultTheme,
  enhanceApp({ app }) {
    // Register custom components
  }
}

Search Configuration ​

VitePress includes built-in local search:

typescript
export default defineConfig({
  themeConfig: {
    search: {
      provider: 'local'
    }
  }
})

Markdown Configuration ​

Customize Markdown processing in config.mts:

typescript
export default defineConfig({
  markdown: {
    theme: 'github-dark',
    lineNumbers: true
  }
})

Internal links use absolute paths without .md extension: /guide/getting-started

See the Writing Guidelines for full link formatting conventions.

Common Issues ​

Problem: Internal links are broken

Solution: Use absolute paths without .md:

markdown
[Link](/guide/page)  # Not: guide/page.md

Problem: Sidebar doesn't appear for new section

Solution: Verify path mapping in config.mts:

typescript
sidebar: {
  '/new-section/': newSectionSidebar
}

Build errors ​

Common causes:

  • Broken internal links
  • Invalid frontmatter YAML
  • Missing images
  • Markdown syntax errors

Fix: Check build output for specific error messages.

Images not loading ​

Problem: Images don't display

Solution:

  1. Place images in docs/assets/
  2. Reference with absolute path: ![Alt](/assets/image.png)

Best Practices ​

Do ✅ ​

  • Use semantic file and folder names
  • Keep sidebar hierarchy shallow (max 3 levels)
  • Test links after adding pages
  • Use frontmatter for metadata
  • Group related pages in folders
  • Build and preview before deploying

Don't ❌ ​

  • Create deep navigation hierarchies
  • Use relative paths for internal links
  • Include .md extension in links
  • Forget to update sidebars
  • Use spaces in filenames (use hyphens)
  • Commit build output to Git

Resources ​