bdbhtmlmanueldocs git:20260827.e9312a3A

Immutable. This exact content is served forever at /api/v1/blob/30df731e88c0bf1f.

---
name: bdbhtmlmanueldocs
description: "Authoritative design system, standalone HTML template, and automated GitHub Pages live hosting workflow for creating neutral, enterprise-grade developer documentation and user manuals in the official Google Antigravity / BDB OS aesthetic (3-column layout, matte dark mode, live search, bilingual DE/EN, pill action tables, TOC scrollspy, and instant CI/CD deployment)."
category: bdb-core
risk: safe
date_added: "2026-08-18"
---

# 🌐 BDB HTML Manual & Live Documentation System (`bdbhtmlmanueldocs`)

This skill codifies the complete specification for building and deploying **neutral, enterprise-grade developer documentation and bilingual user manuals** in the official Google Antigravity / BDB OS aesthetic, complete with automated GitHub Pages live hosting.

---

## 🎯 Core Design Philosophy (Anti-Slop & Neutrality)

1. **Restrained, Professional Aesthetic:**
   - Deep matte charcoal surfaces (`#0f1117`, `#161922`) with subtle crisp borders (`#232733`).
   - High-contrast neutral typography (`#f0f3f6` headers, `#9aa1b2` body).
   - Zero loud rainbow gradients or toy-like cartoon icons.
2. **3-Column Doc Architecture:**
   - **Left Sidebar (260px):** Sticky navigation tree with version badges (`v1.1.0`) and soft pill active highlights.
   - **Center Main (860px max):** Breadcrumbs navigation, title lead, neutral platform tables with action pills (`.pill-btn`), interactive pre-flight checklists, and syntax-highlighted copyable terminal blocks.
   - **Right Sidebar (220px):** "On this page" dynamic Table of Contents tracking active scroll position in real-time.
3. **Zero External Dependencies:**
   - 100% self-contained single-file HTML5 with inlined CSS, vector SVGs, and lightweight vanilla JS.
   - 100% offline-ready, instant load, zero CDN failure risk.
4. **Bilingual Parity (DE / EN):**
   - Native segmented toggle (`DE / EN`) with instant content morphing and `localStorage` persistence.

---

## ⚡ The Live Documentation GitHub Hosting Trick (CI/CD Recipe)

Follow this exact procedure to host any documentation live at `https://<owner>.github.io/<repo>/` in under 60 seconds with automated push-to-deploy:

### 1. Workspace Directory Setup
Place the documentation files at the root of the `docs/` folder:
```bash
docs/
├── index.html          # Main standalone bilingual manual (or symlink)
├── .nojekyll           # Bypasses Jekyll processing to serve raw HTML/CSS assets
└── ...
```

### 2. GitHub Actions Deployment Workflow
Create `.github/workflows/deploy-docs.yml`:
```yaml
name: Deploy Documentation to GitHub Pages

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'
      - '.github/workflows/deploy-docs.yml'
  workflow_dispatch:

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

concurrency:
  group: "pages"
  cancel-in-progress: false

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

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

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: 'docs/'

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

### 3. Switch GitHub Pages Build Type via CLI (One-Liner)
To activate GitHub Actions-based Pages deployment programmatically without opening the browser:
```bash
gh api -X PUT repos/<owner>/<repo>/pages -f build_type=workflow
```

### 4. Trigger & Verify Live URL
```bash
gh workflow run deploy-docs.yml
gh run watch --exit-status
```
The documentation is now live at `https://<owner>.github.io/<repo>/`.

### 5. README.md Badge & Header Link
Add the live documentation badge and banner to the top of `README.md`:
```markdown
[![Documentation](https://img.shields.io/badge/Docs-Live%20Manual-blue?style=flat-square&logo=github)](https://<owner>.github.io/<repo>/)

> 🌐 **Live User Manual & Interactive Guide:** [https://<owner>.github.io/<repo>/](https://<owner>.github.io/<repo>/)
```

---

## 🎨 DTCG Design Tokens

```css
:root {
  /* Layout */
  --header-height: 60px;
  --sidebar-left-width: 260px;
  --sidebar-right-width: 220px;
  --content-max-width: 860px;

  /* Matte Dark Theme */
  --bg-header: #0f1117;
  --bg-body: #0f1117;
  --bg-sidebar: #0f1117;
  --bg-surface: #161922;
  --bg-surface-elevated: #1e222d;
  --bg-card: #161922;
  --bg-table-header: #1c202a;
  
  --border-subtle: #232733;
  --border-strong: #323847;
  
  --text-primary: #f0f3f6;
  --text-secondary: #9aa1b2;
  --text-muted: #656d81;
  --text-link: #58a6ff;
  
  --accent-blue: #3b82f6;
  --accent-blue-subtle: rgba(59, 130, 246, 0.12);
  --accent-pill: #252b38;
  --accent-pill-hover: #32394a;
  
  --success: #3fb950;
  --warning: #d29922;
  --danger: #f85149;
  
  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "Google Sans", Inter, Roboto, sans-serif;
  --font-mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, monospace;
}

[data-theme="light"] {
  --bg-header: #ffffff;
  --bg-body: #ffffff;
  --bg-sidebar: #f8fafc;
  --bg-surface: #f1f5f9;
  --bg-surface-elevated: #e2e8f0;
  --bg-card: #ffffff;
  --bg-table-header: #f8fafc;
  --border-subtle: #e2e8f0;
  --border-strong: #cbd5e1;
  
  --text-primary: #0f172a;
  --text-secondary: #475569;
  --text-muted: #94a3b8;
  --text-link: #2563eb;
  
  --accent-blue: #2563eb;
  --accent-blue-subtle: rgba(37, 99, 235, 0.08);
  --accent-pill: #e2e8f0;
  --accent-pill-hover: #cbd5e1;
}
```

---

## 📁 Turnkey Template Location

Agents can read and duplicate the full standalone template file:
- `~/.agents/skills/bdbhtmlmanueldocs/templates/docs_template.html`