Engineer App

Appearance

Documentation ​

The project uses VitePress for documentation. VitePress is a static site generator built on Vue and Vite, optimized for technical documentation.

Running Locally ​

Start the documentation dev server:

bash
npm run docs

This opens a local server at http://localhost:5173 with hot module replacement.

Available Commands ​

CommandDescription
npm run docsStart dev server with hot reload
npm run docs:buildBuild static site to docs/.vitepress/dist
npm run docs:previewPreview the production build locally

File Structure ​

docs/
├── .vitepress/
│   ├── config.mts        # Site configuration (nav, sidebar, theme)
│   ├── theme/            # Custom theme overrides
│   │   ├── custom.css    # Custom styles
│   │   ├── index.js      # Theme entry point
│   │   └── Layout.vue    # Custom layout component
│   └── dist/             # Build output (gitignored)
├── development/          # Development docs
│   ├── core-concepts/    # This section
│   ├── getting-started/
│   └── ...
├── guide/                # User guide docs
├── architecture/         # Architecture docs
├── claude/               # Claude AI docs
├── public/               # Static assets (images, favicons)
└── index.md              # Homepage

Writing Documentation ​

Creating a New Page ​

  1. Create a .md file in the appropriate directory
  2. Add frontmatter at the top:
markdown
---
title: Page Title
description: Brief description for SEO
outline: deep
---

# Page Title

Content goes here...
  1. Add the page to the sidebar in .vitepress/config.mts

Adding to the Sidebar ​

Edit docs/.vitepress/config.mts:

typescript
sidebar: {
  '/development/': [
    {
      text: 'Core Concepts',
      items: [
        {text: 'Tech Stack', link: '/development/core-concepts/tech-stack'},
        {text: 'New Page', link: '/development/core-concepts/new-page'}, // Add here
      ],
    },
  ],
}

Markdown Features ​

VitePress extends standard Markdown with additional features:

Custom Containers ​

markdown
::: info
Informational message
:::

::: tip
Helpful tip
:::

::: warning
Warning message
:::

::: danger
Critical warning
:::

::: details Click to expand
Hidden content revealed on click
:::

Code Blocks ​

markdown
```typescript
const example = 'syntax highlighted';
```

```typescript{2-3}
// Line highlighting
const highlighted = true;
const alsoHighlighted = true;
const notHighlighted = false;
```

```typescript
// With line numbers
const code = 'example'; 
```

Mermaid Diagrams ​

The site uses vitepress-plugin-mermaid for diagrams:

markdown
```mermaid
flowchart LR
  A[Start] --> B{Decision}
  B -->|Yes| C[Do something]
  B -->|No| D[Do something else]
```

Adding Images ​

  1. Place images in docs/public/
  2. Reference with absolute paths:
markdown
![Alt text](/image-name.png)

Deployment ​

Documentation deploys automatically via GitHub Actions when changes are pushed to the develop branch.

How It Works ​

The workflow in .github/workflows/vitepress-deploy.yml:

  1. Triggers on push to develop or manual dispatch
  2. Builds the VitePress site with npm run docs:build
  3. Deploys to GitHub Pages

Manual Deployment ​

To trigger a deployment manually:

  1. Go to Actions tab in GitHub
  2. Select Deploy VitePress site to Pages
  3. Click Run workflow
  4. Select the develop branch and run

Build Output ​

The production build outputs to docs/.vitepress/dist/. This directory is:

  • Uploaded as a GitHub Pages artifact
  • Deployed to the GitHub Pages environment

Configuration ​

Site Config (config.mts) ​

Key configuration options:

typescript
export default defineConfig({
  title: 'Engineer App',           // Site title
  description: 'Documentation...', // Meta description

  themeConfig: {
    nav: [...],                    // Top navigation
    sidebar: {...},                // Sidebar navigation
    search: {provider: 'local'},   // Built-in search
    socialLinks: [...],            // Header social links
  },
});

Theme Customization ​

Custom styles go in docs/.vitepress/theme/custom.css. The theme extends VitePress defaults via docs/.vitepress/theme/index.js.

Best Practices ​

  1. Keep pages focused - One topic per page, link to related pages
  2. Use frontmatter - Always include title and description
  3. Add to sidebar - New pages should be discoverable via navigation
  4. Use containers - Highlight tips, warnings, and important info
  5. Include code examples - Show, don't just tell
  6. Preview locally - Always run npm run docs before pushing
  7. Use relative links - Link between docs pages with relative paths
  8. Keep images small - Optimize images before adding to public/