Documentation Website Guide

MicroFly's documentation is built using VitePress, a modern static site generator powered by Vite and Vue. It compiles the markdown files in docs/ into a static HTML website with instant client-side full-text search, dark mode, mobile responsiveness, and syntax highlighting.

---

1. Quick Start Commands

Task	Command	Description
Live Development	make docs-dev (or npm run docs:dev)	Starts local dev server at http://localhost:5173 with instant hot reload.
Production Build	make docs (or npm run docs:build)	Compiles static HTML/CSS/JS into docs/.vitepress/dist/.
Local Preview	npm run docs:preview	Serves the production build locally at http://localhost:4173.

---

2. Prerequisites

Ensure Node.js (v18 or newer) and npm are installed:

node -v   # e.g. v20.x or v24.x
npm -v

Install project dependencies (run from the repository root):

npm install

---

3. Local Development

Start the development server:

make docs-dev

Open http://localhost:5173 in your browser. Any edits made to files inside docs/ will automatically update the browser in real time without refreshing.

---

4. Building for Production

Compile the static assets:

make docs

The output is written to:

docs/.vitepress/dist/
├── index.html
├── 404.html
├── assets/
├── getting-started/
├── configuration/
├── guides/
└── reference/

This folder is self-contained and ready to be served by any static web server or CDN.

---

5. Deployment Options

Option A: Hosting on MicroFly (Self-Hosted)

Because MicroFly excels at running native services, you can host the documentation directly on your MicroFly server!

1. Build the documentation site:

   make docs

2. In the docs/.vitepress/dist directory, create an app.toml:

   schema_version = 1
   name = "microfly-docs"
   type = "binary"
   domain = ["docs.example.com"]
   
   [runtime]
   args = ["python3", "-m", "http.server", "{PORT}", "--bind", "127.0.0.1"]
   
   [scale]
   scale_to_zero = true
   idle_timeout = "10m"

3. Deploy to your MicroFly daemon:

   microfly deploy --dir docs/.vitepress/dist microfly-docs

Option B: Deploying to GitHub Pages

Create .github/workflows/deploy-docs.yml to automatically build and publish to GitHub Pages on push:

name: Deploy Documentation to GitHub Pages

on:
  push:
    branches: [master, main]
    paths:
      - 'docs/**'
      - 'package.json'

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: true

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - name: Install Dependencies
        run: npm ci

      - name: Build Documentation Site
        run: npm run docs:build

      - name: Setup Pages
        uses: actions/configure-pages@v4

      - name: Upload Pages Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: docs/.vitepress/dist

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Option C: Cloudflare Pages / Vercel / Netlify

When configuring your project in Cloudflare Pages, Vercel, or Netlify:

• Build Command: npm run docs:build
• Build Output Directory: docs/.vitepress/dist
• Node Version: 20.x or newer

---

6. Customizing the Documentation Site

Adding New Pages

1. Create a new .md file under docs/ (e.g. docs/guides/my-guide.md).
2. Add the page link to the sidebar in [docs/.vitepress/config.mts](file:///home/zhair/Documents/tools/microfly/docs/.vitepress/config.mts):

   {
     text: 'Guides & Workflows',
     items: [
       // ... existing items
       { text: 'My New Guide', link: '/guides/my-guide' }
     ]
   }

Editing Navigation & Search

Configuration settings are located in [docs/.vitepress/config.mts](file:///home/zhair/Documents/tools/microfly/docs/.vitepress/config.mts):

• Site Title: Change title: 'MicroFly'.
• Top Navigation: Edit the themeConfig.nav array.
• Search: Local search is enabled by default (search: { provider: 'local' }).
• Social Links: Edit themeConfig.socialLinks to point to your repository.