LGS Forge

Appearance

Deploying LGS Forge Documentation ​

Quick guide to deploying the documentation site with the neobrutalism theme.

Local Development ​

1. Install Dependencies ​

bash
cd docs
npm install

2. Run Development Server ​

bash
npm run dev

Visit http://localhost:5173 to see the documentation site with live reload.

3. Build for Production ​

bash
npm run build

Build output is in docs/.vitepress/dist/

4. Preview Production Build ​

bash
npm run preview

Vercel provides the best experience for VitePress sites with automatic deployments.

Method 1: Vercel CLI ​

bash
# Install Vercel CLI
npm i -g vercel

# Deploy from docs directory
cd docs
vercel

# Follow prompts to link project
# Deploy to production
vercel --prod

Method 2: Vercel Dashboard ​

  1. Go to vercel.com/new
  2. Import your GitHub repository
  3. Set Root Directory to docs
  4. Vercel auto-detects VitePress
  5. Click Deploy

Configure Custom Domain ​

  1. In Vercel dashboard, go to Settings → Domains
  2. Add docs.lgsforge.com
  3. Configure DNS:
    Type: CNAME
Name: docs
Value: cname.vercel-dns.com
  4. Wait for SSL certificate (automatic)

Deploy to Netlify ​

Method 1: Netlify CLI ​

bash
# Install Netlify CLI
npm i -g netlify-cli

# Build the site
cd docs
npm run build

# Deploy
netlify deploy --prod --dir .vitepress/dist

Method 2: Netlify Dashboard ​

  1. Go to app.netlify.com
  2. Click Add new site → Import an existing project
  3. Connect to GitHub
  4. Configure build settings:
    • Base directory: docs
    • Build command: npm run build
    • Publish directory: docs/.vitepress/dist
  5. Click Deploy

Configure Custom Domain ​

  1. In Netlify dashboard, go to Domain settings
  2. Add custom domain: docs.lgsforge.com
  3. Configure DNS:
    Type: CNAME
Name: docs
Value: <your-site>.netlify.app

Deploy to GitHub Pages ​

1. Create GitHub Action ​

Create .github/workflows/deploy-docs.yml:

yaml
name: Deploy Docs

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'

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

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm
          cache-dependency-path: docs/package-lock.json

      - name: Install dependencies
        working-directory: docs
        run: npm ci

      - name: Build
        working-directory: docs
        run: npm run build

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

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    needs: build
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

2. Enable GitHub Pages ​

  1. Go to repo Settings → Pages
  2. Source: GitHub Actions
  3. Save

3. Configure Custom Domain ​

  1. In Pages settings, add docs.lgsforge.com to Custom domain
  2. Configure DNS:
    Type: CNAME
Name: docs
Value: <username>.github.io

Neobrutalism Theme Features ​

The documentation site includes a custom VitePress theme that matches the LGS Forge app design:

Design System ​

  • Zero border radius - True brutalist aesthetic
  • Thick black borders - 3-4px solid borders on all elements
  • Box shadows - 5px offset shadows (no blur)
  • Bold typography - Space Grotesk for headings (800 weight, uppercase)
  • Purple accent - #C4A1FF primary color
  • Cream background - #F9F5F2
  • Hover effects - Translate on hover to "press" buttons

Typography ​

  • Headings: Space Grotesk, 800 weight, uppercase, 0.05em letter spacing
  • Body: Inter, 600 weight
  • All text: Medium to bold weights for strong visual hierarchy

Components Styled ​

  • Buttons (with press effect)
  • Cards (with thick borders and shadows)
  • Tables (brutalist borders and headers)
  • Code blocks (zero radius, thick borders)
  • Badges (uppercase, thick borders)
  • Navigation (brutalist style)
  • Scrollbars (thick borders, purple thumb)

Responsive Design ​

  • Mobile optimizations (reduced borders/shadows)
  • Scrollable tables on mobile
  • Smaller typography on mobile
  • Flexible button layouts

Troubleshooting ​

Port already in use ​

bash
# Kill process on port 5173
lsof -ti:5173 | xargs kill -9

Build fails ​

bash
# Clear cache and rebuild
rm -rf node_modules .vitepress/cache
npm install
npm run build

Styles not loading ​

Make sure you're importing the custom theme:

  • Check docs/.vitepress/theme/index.js exists
  • Verify custom.css is imported in index.js

Google Fonts not loading ​

Fonts are imported in config.js head section. Check network tab for CORS errors.

Performance Tips ​

  1. Enable Gzip/Brotli compression on your hosting platform
  2. Use CDN - Vercel/Netlify provide this automatically
  3. Optimize images - Keep images in docs/images/ small (<200KB)
  4. Minimize custom CSS - Current theme is optimized

Environment Variables ​

No environment variables required for the docs site.

Monitoring ​

Analytics ​

Add analytics to docs/.vitepress/config.js:

Google Analytics:

javascript
head: [
  ['script', { async: true, src: 'https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX' }],
  ['script', {}, `
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
    gtag('js', new Date());
    gtag('config', 'G-XXXXXXXXXX');
  `]
]

Plausible (Privacy-Friendly):

javascript
head: [
  ['script', { defer: true, 'data-domain': 'docs.lgsforge.com', src: 'https://plausible.io/js/script.js' }]
]

Support ​

Last Updated: January 2026