docs: Add GitHub Wiki and Pages setup automation
Add comprehensive documentation publishing infrastructure with two deployment options: GitHub Wiki (quick) and GitHub Pages (professional). ## New Files ### Setup Scripts - **scripts/setup-wiki.sh** - Automated GitHub Wiki deployment * Clones wiki repository * Creates Home page with navigation * Creates sidebar (_Sidebar.md) * Copies all DOCS/ files * Fixes internal links for wiki format * Auto-commits and pushes - **scripts/setup-github-pages.sh** - GitHub Pages with MkDocs Material * Checks/installs dependencies (Python, MkDocs) * Creates mkdocs.yml configuration * Generates docs/ directory structure * Creates professional home page with cards * Copies and transforms all DOCS/ files * Adds custom CSS matching SecuBox design * Builds preview site * Ready for GitHub Pages deployment ### Documentation - **WIKI-SETUP-GUIDE.md** - Complete setup guide * Comparison of Wiki vs GitHub Pages * Step-by-step instructions for both options * Customization guides * Troubleshooting section * CI/CD automation examples - **scripts/README.md** - Scripts documentation * Quick start for both options * Feature comparison * Update procedures * Troubleshooting ## Features ### GitHub Wiki Option ✅ 2-minute setup ✅ No dependencies (Git only) ✅ Auto-sync from DOCS/ ✅ Sidebar navigation ✅ Archive organization ✅ Link fixing automation ### GitHub Pages Option (Recommended) ✅ MkDocs Material theme ✅ Dark/Light mode support ✅ Professional navigation (tabs + sidebar) ✅ Search functionality ✅ Mermaid diagram support ✅ Mobile responsive ✅ Custom domain support ✅ SEO optimized ✅ Custom CSS matching SecuBox design ✅ Archive section ## Deployment Options **Quick (Wiki):** ```bash ./scripts/setup-wiki.sh # → https://github.com/gkerma/secubox-openwrt/wiki ``` **Professional (Pages):** ```bash ./scripts/setup-github-pages.sh mkdocs serve # Test locally # → https://gkerma.github.io/secubox-openwrt/ ``` ## Benefits ✅ One-command documentation publishing ✅ Two deployment options (quick vs professional) ✅ Automated link fixing for both formats ✅ Complete documentation coverage ✅ Professional appearance (Pages option) ✅ Easy updates (re-run script) ✅ CI/CD ready 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
parent
403283419c
commit
dcdbd7bca6
519
WIKI-SETUP-GUIDE.md
Normal file
519
WIKI-SETUP-GUIDE.md
Normal file
@ -0,0 +1,519 @@
|
||||
# GitHub Wiki & Pages Setup Guide
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Last Updated:** 2025-12-28
|
||||
**Purpose:** Guide for publishing SecuBox documentation online
|
||||
|
||||
---
|
||||
|
||||
## 📚 Two Options for Publishing Documentation
|
||||
|
||||
You have two excellent options for publishing your DOCS/ directory online:
|
||||
|
||||
### Option 1: GitHub Wiki (Simple, Fast)
|
||||
- ✅ **Easy Setup:** Built into GitHub, no configuration needed
|
||||
- ✅ **Quick Deploy:** Simple git push
|
||||
- ✅ **Fast:** Instant updates
|
||||
- ✅ **Search:** Built-in search functionality
|
||||
- ❌ **Limited Theming:** Basic styling only
|
||||
- ❌ **No Custom Domain:** Must use github.com/user/repo/wiki
|
||||
- ❌ **Basic Navigation:** Limited sidebar customization
|
||||
|
||||
**Best for:** Quick documentation, internal team docs, simple navigation
|
||||
|
||||
### Option 2: GitHub Pages with MkDocs (Professional, Feature-Rich)
|
||||
- ✅ **Professional Theme:** Material Design theme
|
||||
- ✅ **Custom Domain:** Can use custom domain (docs.yourdomain.com)
|
||||
- ✅ **Rich Features:** Tabs, search, dark mode, mermaid diagrams
|
||||
- ✅ **Better Navigation:** Multi-level navigation, tabs
|
||||
- ✅ **Mobile Responsive:** Optimized for all devices
|
||||
- ❌ **More Setup:** Requires Python/MkDocs installation
|
||||
- ❌ **Build Step:** Need to build site before deploying
|
||||
|
||||
**Best for:** Public documentation, professional projects, rich content
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Option 1: GitHub Wiki
|
||||
|
||||
```bash
|
||||
# 1. Enable Wiki in GitHub repository settings
|
||||
# https://github.com/gkerma/secubox-openwrt/settings
|
||||
|
||||
# 2. Run setup script
|
||||
chmod +x scripts/setup-wiki.sh
|
||||
./scripts/setup-wiki.sh
|
||||
|
||||
# 3. View your wiki
|
||||
# https://github.com/gkerma/secubox-openwrt/wiki
|
||||
```
|
||||
|
||||
**Time to deploy:** ~2 minutes
|
||||
|
||||
### Option 2: GitHub Pages
|
||||
|
||||
```bash
|
||||
# 1. Install dependencies
|
||||
sudo apt-get install python3 python3-pip
|
||||
pip3 install mkdocs mkdocs-material pymdown-extensions
|
||||
|
||||
# 2. Run setup script
|
||||
chmod +x scripts/setup-github-pages.sh
|
||||
./scripts/setup-github-pages.sh
|
||||
|
||||
# 3. Test locally
|
||||
mkdocs serve
|
||||
# Open: http://127.0.0.1:8000
|
||||
|
||||
# 4. Commit and push
|
||||
git add mkdocs.yml docs/
|
||||
git commit -m "Add GitHub Pages documentation site"
|
||||
git push
|
||||
|
||||
# 5. Enable in GitHub settings
|
||||
# https://github.com/gkerma/secubox-openwrt/settings/pages
|
||||
# Source: Deploy from a branch
|
||||
# Branch: master, Folder: /docs
|
||||
|
||||
# 6. View your site
|
||||
# https://gkerma.github.io/secubox-openwrt/
|
||||
```
|
||||
|
||||
**Time to deploy:** ~10 minutes (first time)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Feature Comparison
|
||||
|
||||
| Feature | GitHub Wiki | GitHub Pages (MkDocs) |
|
||||
|---------|-------------|----------------------|
|
||||
| **Setup Time** | ⚡ 2 min | 🕐 10 min |
|
||||
| **Theme** | Basic | ✨ Material Design |
|
||||
| **Dark Mode** | ❌ No | ✅ Yes |
|
||||
| **Search** | ✅ Yes | ✅ Yes (Better) |
|
||||
| **Mermaid Diagrams** | ✅ Yes | ✅ Yes |
|
||||
| **Code Highlighting** | ✅ Basic | ✅ Advanced |
|
||||
| **Navigation** | 📋 Sidebar | 🎯 Tabs + Sidebar |
|
||||
| **Mobile** | ✅ OK | ✅ Excellent |
|
||||
| **Custom Domain** | ❌ No | ✅ Yes |
|
||||
| **Version Control** | ✅ Separate repo | ✅ Same repo |
|
||||
| **Offline Editing** | ✅ Yes | ✅ Yes |
|
||||
| **Build Required** | ❌ No | ✅ Yes |
|
||||
| **CI/CD Integration** | ⚠️ Manual | ✅ Easy |
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Recommendation
|
||||
|
||||
**For SecuBox, we recommend GitHub Pages with MkDocs** because:
|
||||
|
||||
1. ✨ **Professional appearance** matches your high-quality documentation
|
||||
2. 📱 **Better mobile experience** for users browsing on phones
|
||||
3. 🎨 **Material Design theme** aligns with your indigo/violet color scheme
|
||||
4. 🔍 **Superior search** with instant results
|
||||
5. 🌙 **Dark mode support** matches your design system
|
||||
6. 📊 **Mermaid diagram support** for your 3 architecture diagrams
|
||||
7. 🔗 **Custom domain option** if you want docs.cybermind.fr
|
||||
8. 🚀 **Better SEO** for public documentation
|
||||
|
||||
**However, GitHub Wiki is perfect if:**
|
||||
- You need documentation **now** (2-minute setup)
|
||||
- Internal team use only
|
||||
- Simple navigation is sufficient
|
||||
- Don't want to maintain build pipeline
|
||||
|
||||
---
|
||||
|
||||
## 📖 Detailed Setup Instructions
|
||||
|
||||
### Option 1: GitHub Wiki Setup
|
||||
|
||||
#### Step 1: Enable Wiki
|
||||
|
||||
1. Go to repository settings:
|
||||
```
|
||||
https://github.com/gkerma/secubox-openwrt/settings
|
||||
```
|
||||
|
||||
2. Scroll to "Features" section
|
||||
|
||||
3. Check the "Wikis" checkbox
|
||||
|
||||
4. Save changes
|
||||
|
||||
#### Step 2: Run Setup Script
|
||||
|
||||
```bash
|
||||
cd /path/to/secubox-openwrt
|
||||
|
||||
# Make script executable
|
||||
chmod +x scripts/setup-wiki.sh
|
||||
|
||||
# Run setup
|
||||
./scripts/setup-wiki.sh
|
||||
```
|
||||
|
||||
**What the script does:**
|
||||
1. Clones your wiki repository
|
||||
2. Creates `Home.md` (landing page)
|
||||
3. Creates `_Sidebar.md` (navigation)
|
||||
4. Copies all documentation from DOCS/
|
||||
5. Fixes internal links for wiki format
|
||||
6. Commits and pushes to wiki repository
|
||||
|
||||
#### Step 3: Verify
|
||||
|
||||
Visit: `https://github.com/gkerma/secubox-openwrt/wiki`
|
||||
|
||||
#### Step 4: Update Wiki (Future Changes)
|
||||
|
||||
Whenever you update DOCS/, run:
|
||||
|
||||
```bash
|
||||
./scripts/setup-wiki.sh
|
||||
```
|
||||
|
||||
The script will sync all changes to the wiki.
|
||||
|
||||
---
|
||||
|
||||
### Option 2: GitHub Pages Setup
|
||||
|
||||
#### Step 1: Install Dependencies
|
||||
|
||||
**Ubuntu/Debian:**
|
||||
```bash
|
||||
sudo apt-get update
|
||||
sudo apt-get install python3 python3-pip
|
||||
pip3 install mkdocs mkdocs-material pymdown-extensions
|
||||
```
|
||||
|
||||
**macOS:**
|
||||
```bash
|
||||
brew install python3
|
||||
pip3 install mkdocs mkdocs-material pymdown-extensions
|
||||
```
|
||||
|
||||
**Windows:**
|
||||
```bash
|
||||
# Install Python from python.org first
|
||||
pip install mkdocs mkdocs-material pymdown-extensions
|
||||
```
|
||||
|
||||
#### Step 2: Run Setup Script
|
||||
|
||||
```bash
|
||||
cd /path/to/secubox-openwrt
|
||||
|
||||
# Make script executable
|
||||
chmod +x scripts/setup-github-pages.sh
|
||||
|
||||
# Run setup
|
||||
./scripts/setup-github-pages.sh
|
||||
```
|
||||
|
||||
**What the script does:**
|
||||
1. Creates `mkdocs.yml` configuration with Material theme
|
||||
2. Creates `docs/` directory structure
|
||||
3. Creates beautiful home page with cards
|
||||
4. Copies all documentation from DOCS/
|
||||
5. Fixes internal links for web format
|
||||
6. Creates custom CSS matching your design system
|
||||
7. Builds preview site
|
||||
|
||||
#### Step 3: Test Locally
|
||||
|
||||
```bash
|
||||
mkdocs serve
|
||||
```
|
||||
|
||||
Open browser: `http://127.0.0.1:8000`
|
||||
|
||||
**Navigate and test:**
|
||||
- Check all links work
|
||||
- Verify diagrams render
|
||||
- Test dark/light mode toggle
|
||||
- Try search functionality
|
||||
- Test responsive design (resize browser)
|
||||
|
||||
#### Step 4: Commit and Push
|
||||
|
||||
```bash
|
||||
git add mkdocs.yml docs/
|
||||
git commit -m "Add GitHub Pages documentation site
|
||||
|
||||
- MkDocs Material theme
|
||||
- Complete documentation sync from DOCS/
|
||||
- Custom styling matching SecuBox design
|
||||
- Archive section organized
|
||||
- Search and navigation configured
|
||||
|
||||
🤖 Generated with setup-github-pages.sh
|
||||
"
|
||||
|
||||
git push origin master
|
||||
```
|
||||
|
||||
#### Step 5: Enable GitHub Pages
|
||||
|
||||
1. Go to repository settings:
|
||||
```
|
||||
https://github.com/gkerma/secubox-openwrt/settings/pages
|
||||
```
|
||||
|
||||
2. Configure:
|
||||
- **Source:** Deploy from a branch
|
||||
- **Branch:** `master`
|
||||
- **Folder:** `/docs`
|
||||
|
||||
3. Click **Save**
|
||||
|
||||
4. Wait 2-3 minutes for deployment
|
||||
|
||||
#### Step 6: Verify
|
||||
|
||||
Visit: `https://gkerma.github.io/secubox-openwrt/`
|
||||
|
||||
#### Step 7: (Optional) Custom Domain
|
||||
|
||||
If you own `cybermind.fr` and want `docs.cybermind.fr`:
|
||||
|
||||
1. Add CNAME record in DNS:
|
||||
```
|
||||
docs.cybermind.fr → gkerma.github.io
|
||||
```
|
||||
|
||||
2. Create `docs/CNAME` file:
|
||||
```bash
|
||||
echo "docs.cybermind.fr" > docs/CNAME
|
||||
```
|
||||
|
||||
3. In GitHub Pages settings, set custom domain:
|
||||
```
|
||||
docs.cybermind.fr
|
||||
```
|
||||
|
||||
4. Enable "Enforce HTTPS"
|
||||
|
||||
#### Step 8: Update Docs (Future Changes)
|
||||
|
||||
Whenever you update DOCS/:
|
||||
|
||||
```bash
|
||||
# Update docs
|
||||
# (edit files in DOCS/)
|
||||
|
||||
# Re-run sync script
|
||||
./scripts/setup-github-pages.sh
|
||||
|
||||
# Or manually copy changed files:
|
||||
cp DOCS/CHANGED-FILE.md docs/changed-file.md
|
||||
|
||||
# Build and test
|
||||
mkdocs serve
|
||||
|
||||
# Commit and push
|
||||
git add docs/
|
||||
git commit -m "Update documentation"
|
||||
git push
|
||||
```
|
||||
|
||||
GitHub Pages will auto-rebuild and deploy in ~2 minutes.
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Automated Sync (CI/CD)
|
||||
|
||||
### For GitHub Pages
|
||||
|
||||
Create `.github/workflows/deploy-docs.yml`:
|
||||
|
||||
```yaml
|
||||
name: Deploy Documentation
|
||||
|
||||
on:
|
||||
push:
|
||||
branches:
|
||||
- master
|
||||
paths:
|
||||
- 'DOCS/**'
|
||||
- 'mkdocs.yml'
|
||||
|
||||
jobs:
|
||||
deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
|
||||
- name: Setup Python
|
||||
uses: actions/setup-python@v4
|
||||
with:
|
||||
python-version: 3.x
|
||||
|
||||
- name: Install dependencies
|
||||
run: |
|
||||
pip install mkdocs mkdocs-material pymdown-extensions
|
||||
|
||||
- name: Sync DOCS to docs/
|
||||
run: |
|
||||
./scripts/setup-github-pages.sh
|
||||
|
||||
- name: Deploy to GitHub Pages
|
||||
run: mkdocs gh-deploy --force
|
||||
```
|
||||
|
||||
Now documentation auto-updates on every push to DOCS/!
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Customization
|
||||
|
||||
### GitHub Wiki
|
||||
|
||||
**Edit sidebar:**
|
||||
```bash
|
||||
# Clone wiki
|
||||
git clone https://github.com/gkerma/secubox-openwrt.wiki.git
|
||||
|
||||
# Edit sidebar
|
||||
vim _Sidebar.md
|
||||
|
||||
# Commit and push
|
||||
git add _Sidebar.md
|
||||
git commit -m "Update sidebar"
|
||||
git push
|
||||
```
|
||||
|
||||
### GitHub Pages
|
||||
|
||||
**Edit theme colors:**
|
||||
```yaml
|
||||
# mkdocs.yml
|
||||
theme:
|
||||
palette:
|
||||
primary: indigo # Change to: blue, red, green, etc.
|
||||
accent: purple # Change to: pink, cyan, etc.
|
||||
```
|
||||
|
||||
**Add custom CSS:**
|
||||
```css
|
||||
/* docs/stylesheets/extra.css */
|
||||
:root {
|
||||
--md-primary-fg-color: #6366f1; /* Your custom color */
|
||||
}
|
||||
```
|
||||
|
||||
**Add custom logo:**
|
||||
```yaml
|
||||
# mkdocs.yml
|
||||
theme:
|
||||
logo: assets/logo.png
|
||||
favicon: assets/favicon.png
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📊 Analytics
|
||||
|
||||
### GitHub Pages
|
||||
|
||||
Add Google Analytics to `mkdocs.yml`:
|
||||
|
||||
```yaml
|
||||
extra:
|
||||
analytics:
|
||||
provider: google
|
||||
property: G-XXXXXXXXXX
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### GitHub Wiki
|
||||
|
||||
**Problem:** Wiki not showing
|
||||
|
||||
**Solution:**
|
||||
1. Ensure Wiki is enabled in repository settings
|
||||
2. Check that at least `Home.md` exists
|
||||
3. Verify push was successful: `git log` in wiki repo
|
||||
|
||||
**Problem:** Links broken
|
||||
|
||||
**Solution:**
|
||||
Wiki uses different link format:
|
||||
- ✅ Correct: `[Text](Page-Name)`
|
||||
- ❌ Wrong: `[Text](./file.md)`
|
||||
|
||||
Run `./scripts/setup-wiki.sh` to fix all links.
|
||||
|
||||
### GitHub Pages
|
||||
|
||||
**Problem:** Site not building
|
||||
|
||||
**Solution:**
|
||||
1. Check GitHub Actions tab for build errors
|
||||
2. Test locally: `mkdocs build --strict`
|
||||
3. Verify `mkdocs.yml` syntax
|
||||
|
||||
**Problem:** Diagrams not rendering
|
||||
|
||||
**Solution:**
|
||||
Add to `mkdocs.yml`:
|
||||
```yaml
|
||||
markdown_extensions:
|
||||
- pymdownx.superfences:
|
||||
custom_fences:
|
||||
- name: mermaid
|
||||
class: mermaid
|
||||
format: !!python/name:pymdownx.superfences.fence_code_format
|
||||
```
|
||||
|
||||
**Problem:** Links broken
|
||||
|
||||
**Solution:**
|
||||
Use relative links without `./`:
|
||||
- ✅ Correct: `[Text](page-name.md)`
|
||||
- ❌ Wrong: `[Text](./PAGE-NAME.md)`
|
||||
|
||||
Run `./scripts/setup-github-pages.sh` to fix all links.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Our Recommendation
|
||||
|
||||
**For SecuBox: Use GitHub Pages with MkDocs Material**
|
||||
|
||||
The professional appearance, superior navigation, and rich features perfectly complement your high-quality documentation and modern design system.
|
||||
|
||||
**Quick start:**
|
||||
```bash
|
||||
chmod +x scripts/setup-github-pages.sh
|
||||
./scripts/setup-github-pages.sh
|
||||
mkdocs serve # Test locally
|
||||
# Then follow steps 4-6 above to deploy
|
||||
```
|
||||
|
||||
**Result:** Professional documentation site at `https://gkerma.github.io/secubox-openwrt/`
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
**Issues with scripts:**
|
||||
- Check script output for errors
|
||||
- Ensure all dependencies installed
|
||||
- Verify DOCS/ directory exists
|
||||
|
||||
**Need help?**
|
||||
- Create GitHub issue
|
||||
- Email: support@cybermind.fr
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-12-28
|
||||
**Scripts Location:** `scripts/`
|
||||
**Maintainer:** CyberMind.fr
|
||||
291
scripts/README.md
Normal file
291
scripts/README.md
Normal file
@ -0,0 +1,291 @@
|
||||
# Documentation Publishing Scripts
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Last Updated:** 2025-12-28
|
||||
**Purpose:** Automated scripts for publishing SecuBox documentation
|
||||
|
||||
---
|
||||
|
||||
## 📜 Available Scripts
|
||||
|
||||
### 1. setup-wiki.sh
|
||||
**Purpose:** Sync DOCS/ to GitHub Wiki
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./scripts/setup-wiki.sh
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Clones wiki repository
|
||||
- Creates Home page with navigation
|
||||
- Creates sidebar
|
||||
- Copies all documentation files
|
||||
- Fixes internal links for wiki format
|
||||
- Commits and pushes to wiki
|
||||
|
||||
**Requirements:**
|
||||
- Git installed
|
||||
- Wiki enabled in GitHub repository
|
||||
- SSH access to GitHub
|
||||
|
||||
**Time:** ~2 minutes
|
||||
|
||||
---
|
||||
|
||||
### 2. setup-github-pages.sh
|
||||
**Purpose:** Create GitHub Pages site with MkDocs Material theme
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
./scripts/setup-github-pages.sh
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
- Installs MkDocs if needed
|
||||
- Creates mkdocs.yml configuration
|
||||
- Generates docs/ directory structure
|
||||
- Creates beautiful home page
|
||||
- Copies all documentation files
|
||||
- Fixes internal links for web
|
||||
- Builds preview site
|
||||
|
||||
**Requirements:**
|
||||
- Python 3.x installed
|
||||
- pip3 installed
|
||||
- ~100MB disk space
|
||||
|
||||
**Time:** ~10 minutes (first time)
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Which Script to Use?
|
||||
|
||||
### Use `setup-wiki.sh` if:
|
||||
- ✅ You want quick setup (2 minutes)
|
||||
- ✅ Internal documentation only
|
||||
- ✅ Simple navigation is sufficient
|
||||
- ✅ No theming needed
|
||||
|
||||
### Use `setup-github-pages.sh` if:
|
||||
- ✅ You want professional appearance
|
||||
- ✅ Public documentation
|
||||
- ✅ Custom domain support needed
|
||||
- ✅ Dark mode support wanted
|
||||
- ✅ Better mobile experience needed
|
||||
|
||||
**Our recommendation:** Use GitHub Pages for SecuBox's professional documentation.
|
||||
|
||||
See [WIKI-SETUP-GUIDE.md](../WIKI-SETUP-GUIDE.md) for complete setup instructions.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Option 1: GitHub Wiki
|
||||
|
||||
```bash
|
||||
# 1. Enable Wiki in GitHub settings
|
||||
# 2. Run script
|
||||
./scripts/setup-wiki.sh
|
||||
|
||||
# 3. View at:
|
||||
# https://github.com/gkerma/secubox-openwrt/wiki
|
||||
```
|
||||
|
||||
### Option 2: GitHub Pages (Recommended)
|
||||
|
||||
```bash
|
||||
# 1. Install dependencies
|
||||
sudo apt-get install python3 python3-pip
|
||||
pip3 install mkdocs mkdocs-material pymdown-extensions
|
||||
|
||||
# 2. Run script
|
||||
./scripts/setup-github-pages.sh
|
||||
|
||||
# 3. Test locally
|
||||
mkdocs serve
|
||||
|
||||
# 4. Commit and push
|
||||
git add mkdocs.yml docs/
|
||||
git commit -m "Add GitHub Pages documentation"
|
||||
git push
|
||||
|
||||
# 5. Enable in GitHub settings
|
||||
# Settings → Pages → Source: master, Folder: /docs
|
||||
|
||||
# 6. View at:
|
||||
# https://gkerma.github.io/secubox-openwrt/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📋 Script Features
|
||||
|
||||
### setup-wiki.sh
|
||||
|
||||
| Feature | Status |
|
||||
|---------|--------|
|
||||
| Auto-clone wiki repo | ✅ |
|
||||
| Create Home page | ✅ |
|
||||
| Create sidebar navigation | ✅ |
|
||||
| Copy all docs | ✅ |
|
||||
| Fix internal links | ✅ |
|
||||
| Archive organization | ✅ |
|
||||
| Auto-commit & push | ✅ |
|
||||
| Error handling | ✅ |
|
||||
|
||||
### setup-github-pages.sh
|
||||
|
||||
| Feature | Status |
|
||||
|---------|--------|
|
||||
| Dependency check | ✅ |
|
||||
| Auto-install MkDocs | ✅ |
|
||||
| Material theme | ✅ |
|
||||
| Dark/Light mode | ✅ |
|
||||
| Search functionality | ✅ |
|
||||
| Mermaid diagrams | ✅ |
|
||||
| Mobile responsive | ✅ |
|
||||
| Custom CSS | ✅ |
|
||||
| Archive organization | ✅ |
|
||||
| Build preview | ✅ |
|
||||
| Link fixing | ✅ |
|
||||
| Error handling | ✅ |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Updating Documentation
|
||||
|
||||
### For GitHub Wiki
|
||||
|
||||
Just run the script again:
|
||||
```bash
|
||||
./scripts/setup-wiki.sh
|
||||
```
|
||||
|
||||
All changes in DOCS/ will be synced to wiki.
|
||||
|
||||
### For GitHub Pages
|
||||
|
||||
```bash
|
||||
# Option 1: Full re-sync
|
||||
./scripts/setup-github-pages.sh
|
||||
|
||||
# Option 2: Manual update
|
||||
cp DOCS/CHANGED-FILE.md docs/changed-file.md
|
||||
mkdocs build
|
||||
git add docs/
|
||||
git commit -m "Update docs"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### setup-wiki.sh
|
||||
|
||||
**Error: "Wiki repository doesn't exist"**
|
||||
- Enable Wiki in GitHub repository settings first
|
||||
- URL: https://github.com/gkerma/secubox-openwrt/settings
|
||||
|
||||
**Error: "Permission denied"**
|
||||
- Ensure SSH key is configured for GitHub
|
||||
- Test: `ssh -T git@github.com`
|
||||
|
||||
### setup-github-pages.sh
|
||||
|
||||
**Error: "mkdocs: command not found"**
|
||||
- Install MkDocs: `pip3 install mkdocs mkdocs-material`
|
||||
- Or run script again (auto-installs)
|
||||
|
||||
**Error: "No module named 'material'"**
|
||||
- Install theme: `pip3 install mkdocs-material`
|
||||
|
||||
**Error: "Build failed"**
|
||||
- Check mkdocs.yml syntax
|
||||
- Test: `mkdocs build --strict`
|
||||
- Check Python version: `python3 --version` (need 3.6+)
|
||||
|
||||
---
|
||||
|
||||
## 📊 Comparison
|
||||
|
||||
| Aspect | Wiki Script | Pages Script |
|
||||
|--------|-------------|--------------|
|
||||
| **Setup Time** | 2 min | 10 min |
|
||||
| **Dependencies** | Git only | Python, MkDocs |
|
||||
| **Result** | Basic wiki | Professional site |
|
||||
| **Theme** | Default | Material Design |
|
||||
| **Features** | Basic | Advanced |
|
||||
| **Mobile** | OK | Excellent |
|
||||
| **SEO** | Basic | Good |
|
||||
| **Custom Domain** | No | Yes |
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Customization
|
||||
|
||||
### Wiki
|
||||
|
||||
Edit generated files in wiki repository:
|
||||
```bash
|
||||
git clone https://github.com/gkerma/secubox-openwrt.wiki.git
|
||||
cd secubox-openwrt.wiki
|
||||
# Edit _Sidebar.md, Home.md, etc.
|
||||
git commit -am "Customize wiki"
|
||||
git push
|
||||
```
|
||||
|
||||
### GitHub Pages
|
||||
|
||||
Edit mkdocs.yml and docs/stylesheets/extra.css:
|
||||
```bash
|
||||
# Change theme colors
|
||||
vim mkdocs.yml
|
||||
|
||||
# Change custom styles
|
||||
vim docs/stylesheets/extra.css
|
||||
|
||||
# Rebuild
|
||||
mkdocs build
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
**Script Issues:**
|
||||
- Check error messages in script output
|
||||
- Verify dependencies installed
|
||||
- Ensure DOCS/ directory exists
|
||||
|
||||
**Need Help:**
|
||||
- See: [WIKI-SETUP-GUIDE.md](../WIKI-SETUP-GUIDE.md)
|
||||
- Create GitHub issue
|
||||
- Email: support@cybermind.fr
|
||||
|
||||
---
|
||||
|
||||
## 📝 Script Maintenance
|
||||
|
||||
**Update scripts:**
|
||||
```bash
|
||||
# Edit scripts
|
||||
vim scripts/setup-wiki.sh
|
||||
vim scripts/setup-github-pages.sh
|
||||
|
||||
# Test changes
|
||||
./scripts/setup-wiki.sh --dry-run # (if implemented)
|
||||
|
||||
# Commit
|
||||
git add scripts/
|
||||
git commit -m "Update wiki setup scripts"
|
||||
git push
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-12-28
|
||||
**Maintainer:** CyberMind.fr
|
||||
**License:** Apache-2.0
|
||||
500
scripts/setup-github-pages.sh
Executable file
500
scripts/setup-github-pages.sh
Executable file
@ -0,0 +1,500 @@
|
||||
#!/bin/bash
|
||||
# GitHub Pages Setup Script (Alternative to Wiki)
|
||||
# Creates a docs/ site using GitHub Pages with MkDocs
|
||||
|
||||
set -e
|
||||
|
||||
DOCS_DIR="./DOCS"
|
||||
SITE_DIR="./docs"
|
||||
|
||||
echo "🔧 SecuBox GitHub Pages Setup"
|
||||
echo "==============================="
|
||||
echo ""
|
||||
|
||||
# Check if docs directory exists
|
||||
if [ ! -d "$DOCS_DIR" ]; then
|
||||
echo "❌ Error: DOCS directory not found"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "📦 Checking dependencies..."
|
||||
|
||||
# Check for Python and pip
|
||||
if ! command -v python3 &> /dev/null; then
|
||||
echo "❌ Python 3 is required but not installed."
|
||||
echo " Install: sudo apt-get install python3 python3-pip"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if ! command -v pip3 &> /dev/null; then
|
||||
echo "❌ pip3 is required but not installed."
|
||||
echo " Install: sudo apt-get install python3-pip"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Install mkdocs if not present
|
||||
if ! command -v mkdocs &> /dev/null; then
|
||||
echo "📥 Installing MkDocs..."
|
||||
pip3 install mkdocs mkdocs-material pymdown-extensions
|
||||
else
|
||||
echo "✅ MkDocs already installed"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo "📋 Creating GitHub Pages structure..."
|
||||
|
||||
# Create mkdocs.yml configuration
|
||||
cat > mkdocs.yml << 'EOF'
|
||||
site_name: SecuBox Documentation
|
||||
site_description: OpenWrt LuCI Security & Management Suite
|
||||
site_author: CyberMind.fr
|
||||
site_url: https://gkerma.github.io/secubox-openwrt/
|
||||
|
||||
repo_name: gkerma/secubox-openwrt
|
||||
repo_url: https://github.com/gkerma/secubox-openwrt
|
||||
edit_uri: edit/master/DOCS/
|
||||
|
||||
theme:
|
||||
name: material
|
||||
palette:
|
||||
# Light mode
|
||||
- media: "(prefers-color-scheme: light)"
|
||||
scheme: default
|
||||
primary: indigo
|
||||
accent: purple
|
||||
toggle:
|
||||
icon: material/brightness-7
|
||||
name: Switch to dark mode
|
||||
# Dark mode
|
||||
- media: "(prefers-color-scheme: dark)"
|
||||
scheme: slate
|
||||
primary: indigo
|
||||
accent: purple
|
||||
toggle:
|
||||
icon: material/brightness-4
|
||||
name: Switch to light mode
|
||||
|
||||
features:
|
||||
- navigation.instant
|
||||
- navigation.tracking
|
||||
- navigation.tabs
|
||||
- navigation.tabs.sticky
|
||||
- navigation.sections
|
||||
- navigation.expand
|
||||
- navigation.top
|
||||
- search.suggest
|
||||
- search.highlight
|
||||
- content.code.copy
|
||||
- content.code.annotate
|
||||
|
||||
icon:
|
||||
repo: fontawesome/brands/github
|
||||
edit: material/pencil
|
||||
view: material/eye
|
||||
|
||||
font:
|
||||
text: Inter
|
||||
code: JetBrains Mono
|
||||
|
||||
extra_css:
|
||||
- stylesheets/extra.css
|
||||
|
||||
extra:
|
||||
social:
|
||||
- icon: fontawesome/brands/github
|
||||
link: https://github.com/gkerma/secubox-openwrt
|
||||
- icon: fontawesome/solid/globe
|
||||
link: https://secubox.cybermood.eu
|
||||
|
||||
version:
|
||||
provider: mike
|
||||
|
||||
markdown_extensions:
|
||||
- pymdownx.highlight:
|
||||
anchor_linenums: true
|
||||
- pymdownx.inlinehilite
|
||||
- pymdownx.snippets
|
||||
- pymdownx.superfences:
|
||||
custom_fences:
|
||||
- name: mermaid
|
||||
class: mermaid
|
||||
format: !!python/name:pymdownx.superfences.fence_code_format
|
||||
- pymdownx.tabbed:
|
||||
alternate_style: true
|
||||
- pymdownx.tasklist:
|
||||
custom_checkbox: true
|
||||
- admonition
|
||||
- pymdownx.details
|
||||
- attr_list
|
||||
- md_in_html
|
||||
- tables
|
||||
- toc:
|
||||
permalink: true
|
||||
|
||||
nav:
|
||||
- Home: index.md
|
||||
- Getting Started:
|
||||
- Quick Start: quick-start.md
|
||||
- Documentation Index: documentation-index.md
|
||||
|
||||
- Development:
|
||||
- Development Guidelines: development-guidelines.md
|
||||
- Code Templates: code-templates.md
|
||||
- Module Implementation: module-implementation-guide.md
|
||||
|
||||
- Reference:
|
||||
- RPCD & Architecture: claude.md
|
||||
- Validation Guide: validation-guide.md
|
||||
- Permissions Guide: permissions-guide.md
|
||||
- LuCI Development: luci-development-reference.md
|
||||
|
||||
- Modules:
|
||||
- Module Status: module-status.md
|
||||
- Feature Prompts: feature-regeneration-prompts.md
|
||||
|
||||
- Tools & Roadmap:
|
||||
- TODO Roadmap: todo-analyse.md
|
||||
|
||||
- Archive:
|
||||
- Archive Index: archive/index.md
|
||||
- Build Issues: archive/build-issues.md
|
||||
- Completion Report: archive/completion-report.md
|
||||
- Module Enable/Disable: archive/module-enable-disable-design.md
|
||||
EOF
|
||||
|
||||
# Create docs directory structure
|
||||
echo "📁 Creating docs/ directory..."
|
||||
rm -rf "$SITE_DIR"
|
||||
mkdir -p "$SITE_DIR"
|
||||
mkdir -p "$SITE_DIR/archive"
|
||||
mkdir -p "$SITE_DIR/stylesheets"
|
||||
|
||||
# Create index page (home)
|
||||
cat > "$SITE_DIR/index.md" << 'EOF'
|
||||
# SecuBox Documentation
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Last Updated:** 2025-12-28
|
||||
**Project:** OpenWrt LuCI Security & Management Suite
|
||||
|
||||
Welcome to the SecuBox documentation! This comprehensive guide covers all aspects of developing, deploying, and maintaining SecuBox modules.
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ What is SecuBox?
|
||||
|
||||
SecuBox is a comprehensive **security and network management suite for OpenWrt** consisting of **15 LuCI application modules** that provide:
|
||||
|
||||
- **Security Monitoring** - CrowdSec intrusion prevention, Netdata metrics
|
||||
- **Network Intelligence** - Deep packet inspection, traffic classification
|
||||
- **Access Control** - Captive portal, authentication, VPN management
|
||||
- **Performance Optimization** - QoS, bandwidth management, caching
|
||||
- **System Administration** - Centralized dashboard, service management
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Navigation
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
|
||||
- :fontawesome-solid-rocket:{ .lg .middle } **Getting Started**
|
||||
|
||||
---
|
||||
|
||||
New to SecuBox? Start here!
|
||||
|
||||
[:octicons-arrow-right-24: Quick Start Guide](quick-start.md)
|
||||
|
||||
- :fontawesome-solid-book:{ .lg .middle } **Development Guide**
|
||||
|
||||
---
|
||||
|
||||
Complete development reference with architecture diagrams
|
||||
|
||||
[:octicons-arrow-right-24: Development Guidelines](development-guidelines.md)
|
||||
|
||||
- :fontawesome-solid-code:{ .lg .middle } **Code Templates**
|
||||
|
||||
---
|
||||
|
||||
Working examples and implementation patterns
|
||||
|
||||
[:octicons-arrow-right-24: Code Templates](code-templates.md)
|
||||
|
||||
- :fontawesome-solid-list-check:{ .lg .middle } **Validation**
|
||||
|
||||
---
|
||||
|
||||
Module validation and testing workflows
|
||||
|
||||
[:octicons-arrow-right-24: Validation Guide](validation-guide.md)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## 📦 15 Module Suite
|
||||
|
||||
### Core Control (2 modules)
|
||||
- **SecuBox Central Hub** - Main dashboard and module management
|
||||
- **System Hub** - System administration (health, services, logs, backup, etc.)
|
||||
|
||||
### Security & Monitoring (2 modules)
|
||||
- **CrowdSec Dashboard** - Intrusion prevention and threat intelligence
|
||||
- **Netdata Dashboard** - Real-time system monitoring
|
||||
|
||||
### Network Intelligence (2 modules)
|
||||
- **Netifyd Dashboard** - Deep packet inspection and classification
|
||||
- **Network Modes** - Network profile management
|
||||
|
||||
### VPN & Access Control (3 modules)
|
||||
- **WireGuard Dashboard** - VPN tunnel management
|
||||
- **Client Guardian** - Network access control and captive portal
|
||||
- **Auth Guardian** - Authentication system
|
||||
|
||||
### Bandwidth & Traffic (2 modules)
|
||||
- **Bandwidth Manager** - QoS and bandwidth quotas
|
||||
- **Traffic Shaper** - Advanced traffic shaping
|
||||
|
||||
### Performance & Services (2 modules)
|
||||
- **CDN Cache** - Content delivery network proxy cache
|
||||
- **VHost Manager** - Virtual host configuration
|
||||
|
||||
### System Optimization (2 modules)
|
||||
- **Media Flow** - Media traffic optimization
|
||||
- **KSM Manager** - Kernel same-page merging
|
||||
|
||||
[View Module Status →](module-status.md){ .md-button .md-button--primary }
|
||||
|
||||
---
|
||||
|
||||
## 🎨 Design System
|
||||
|
||||
SecuBox uses a modern, consistent design system:
|
||||
|
||||
- **Color Palette:** Indigo/Violet gradients with dark mode support
|
||||
- **Typography:** Inter (text) + JetBrains Mono (code/values)
|
||||
- **Components:** Cards, badges, buttons with gradient effects
|
||||
- **Layout:** Responsive grid system
|
||||
|
||||
See the [Design System section](development-guidelines.md#design-system--ui-guidelines) for complete specifications.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Development Workflow
|
||||
|
||||
!!! warning "Critical Rules"
|
||||
1. **RPCD Naming:** Script name must match ubus object (`luci.module-name`)
|
||||
2. **Menu Paths:** Must match view file locations exactly
|
||||
3. **Permissions:** 755 for RPCD scripts, 644 for CSS/JS
|
||||
4. **Validation:** Always run `./secubox-tools/validate-modules.sh` before commit
|
||||
|
||||
### Development Tools
|
||||
|
||||
```bash
|
||||
# Validate all modules (7 automated checks)
|
||||
./secubox-tools/validate-modules.sh
|
||||
|
||||
# Fix file permissions automatically
|
||||
./secubox-tools/fix-permissions.sh --local
|
||||
|
||||
# Build packages locally
|
||||
./secubox-tools/local-build.sh build luci-app-module-name
|
||||
```
|
||||
|
||||
[Complete Development Workflow →](development-guidelines.md#deployment-procedures){ .md-button }
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Live Demo
|
||||
|
||||
Experience SecuBox in action:
|
||||
|
||||
**Production Demo:** [https://secubox.cybermood.eu](https://secubox.cybermood.eu)
|
||||
|
||||
- Main dashboard: `/`
|
||||
- System Hub: `/system-hub`
|
||||
- CrowdSec: `/crowdsec`
|
||||
- All 15 modules accessible
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation Sections
|
||||
|
||||
### For New Contributors
|
||||
1. [Quick Start Guide](quick-start.md) - Essential rules and commands
|
||||
2. [Development Guidelines](development-guidelines.md) - Complete reference
|
||||
3. [CLAUDE.md](claude.md) - Build system and architecture
|
||||
|
||||
### For AI-Assisted Development
|
||||
1. [Module Implementation Guide](module-implementation-guide.md) - Step-by-step workflow
|
||||
2. [Feature Regeneration Prompts](feature-regeneration-prompts.md) - AI prompts for all modules
|
||||
3. [Code Templates](code-templates.md) - Implementation patterns
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support & Resources
|
||||
|
||||
- **GitHub Repository:** [gkerma/secubox-openwrt](https://github.com/gkerma/secubox-openwrt)
|
||||
- **Documentation Issues:** [GitHub Issues](https://github.com/gkerma/secubox-openwrt/issues)
|
||||
- **Technical Support:** support@cybermind.fr
|
||||
- **Company:** CyberMind.fr
|
||||
|
||||
---
|
||||
|
||||
## 📝 License
|
||||
|
||||
Apache-2.0
|
||||
|
||||
---
|
||||
|
||||
<small>**Last Updated:** 2025-12-28 | **Maintainer:** CyberMind.fr</small>
|
||||
EOF
|
||||
|
||||
# Copy documentation files with lowercase names (convention for web)
|
||||
echo "📄 Copying documentation files..."
|
||||
cp "$DOCS_DIR/QUICK-START.md" "$SITE_DIR/quick-start.md"
|
||||
cp "$DOCS_DIR/DEVELOPMENT-GUIDELINES.md" "$SITE_DIR/development-guidelines.md"
|
||||
cp "$DOCS_DIR/DOCUMENTATION-INDEX.md" "$SITE_DIR/documentation-index.md"
|
||||
cp "$DOCS_DIR/CODE-TEMPLATES.md" "$SITE_DIR/code-templates.md"
|
||||
cp "$DOCS_DIR/CLAUDE.md" "$SITE_DIR/claude.md"
|
||||
cp "$DOCS_DIR/VALIDATION-GUIDE.md" "$SITE_DIR/validation-guide.md"
|
||||
cp "$DOCS_DIR/PERMISSIONS-GUIDE.md" "$SITE_DIR/permissions-guide.md"
|
||||
cp "$DOCS_DIR/FEATURE-REGENERATION-PROMPTS.md" "$SITE_DIR/feature-regeneration-prompts.md"
|
||||
cp "$DOCS_DIR/MODULE-IMPLEMENTATION-GUIDE.md" "$SITE_DIR/module-implementation-guide.md"
|
||||
cp "$DOCS_DIR/MODULE_STATUS.md" "$SITE_DIR/module-status.md"
|
||||
cp "$DOCS_DIR/LUCI_DEVELOPMENT_REFERENCE.md" "$SITE_DIR/luci-development-reference.md"
|
||||
cp "TODO-ANALYSE.md" "$SITE_DIR/todo-analyse.md"
|
||||
|
||||
# Create archive index
|
||||
cat > "$SITE_DIR/archive/index.md" << 'EOF'
|
||||
# Documentation Archive
|
||||
|
||||
Historical and completed documentation.
|
||||
|
||||
## Purpose
|
||||
|
||||
This archive contains documents that:
|
||||
- Represent completed project milestones
|
||||
- Describe implemented features
|
||||
- Document resolved issues
|
||||
|
||||
## Archived Documents
|
||||
|
||||
- [Build Issues](build-issues.md) - Historical build troubleshooting (resolved)
|
||||
- [Completion Report](completion-report.md) - Project completion milestone
|
||||
- [Module Enable/Disable Design](module-enable-disable-design.md) - Feature design (implemented)
|
||||
|
||||
## Archive Policy
|
||||
|
||||
Documents are archived when:
|
||||
1. ✅ Feature/project is completed
|
||||
2. ✅ Information is outdated but historically valuable
|
||||
3. ✅ Content has been migrated to active documentation
|
||||
4. ✅ Document serves as historical reference only
|
||||
|
||||
---
|
||||
|
||||
[← Back to Home](../index.md){ .md-button }
|
||||
EOF
|
||||
|
||||
cp "$DOCS_DIR/archive/BUILD_ISSUES.md" "$SITE_DIR/archive/build-issues.md"
|
||||
cp "$DOCS_DIR/archive/COMPLETION_REPORT.md" "$SITE_DIR/archive/completion-report.md"
|
||||
cp "$DOCS_DIR/archive/MODULE-ENABLE-DISABLE-DESIGN.md" "$SITE_DIR/archive/module-enable-disable-design.md"
|
||||
|
||||
# Create custom CSS
|
||||
cat > "$SITE_DIR/stylesheets/extra.css" << 'EOF'
|
||||
/* SecuBox custom styling */
|
||||
|
||||
:root {
|
||||
--md-primary-fg-color: #6366f1;
|
||||
--md-accent-fg-color: #8b5cf6;
|
||||
}
|
||||
|
||||
/* Code blocks */
|
||||
.highlight {
|
||||
border-radius: 0.375rem;
|
||||
}
|
||||
|
||||
/* Cards grid */
|
||||
.grid.cards {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(240px, 1fr));
|
||||
gap: 1rem;
|
||||
margin: 1.5rem 0;
|
||||
}
|
||||
|
||||
.grid.cards > * {
|
||||
border: 1px solid var(--md-default-fg-color--lightest);
|
||||
border-radius: 0.375rem;
|
||||
padding: 1rem;
|
||||
transition: transform 0.2s, box-shadow 0.2s;
|
||||
}
|
||||
|
||||
.grid.cards > *:hover {
|
||||
transform: translateY(-2px);
|
||||
box-shadow: 0 4px 12px rgba(0, 0, 0, 0.1);
|
||||
}
|
||||
|
||||
/* Gradient headings */
|
||||
h1 {
|
||||
background: linear-gradient(135deg, #6366f1, #8b5cf6);
|
||||
-webkit-background-clip: text;
|
||||
-webkit-text-fill-color: transparent;
|
||||
background-clip: text;
|
||||
}
|
||||
|
||||
/* Admonitions */
|
||||
.md-typeset .admonition {
|
||||
border-radius: 0.375rem;
|
||||
}
|
||||
EOF
|
||||
|
||||
echo ""
|
||||
echo "🔧 Fixing internal links for GitHub Pages..."
|
||||
# Convert relative links to work with GitHub Pages
|
||||
find "$SITE_DIR" -name "*.md" -type f -exec sed -i \
|
||||
-e 's|\](\.\/QUICK-START\.md)|](quick-start.md)|g' \
|
||||
-e 's|\](\.\/DEVELOPMENT-GUIDELINES\.md)|](development-guidelines.md)|g' \
|
||||
-e 's|\](\.\/DOCUMENTATION-INDEX\.md)|](documentation-index.md)|g' \
|
||||
-e 's|\](\.\/CODE-TEMPLATES\.md)|](code-templates.md)|g' \
|
||||
-e 's|\](\.\/CLAUDE\.md)|](claude.md)|g' \
|
||||
-e 's|\](\.\/VALIDATION-GUIDE\.md)|](validation-guide.md)|g' \
|
||||
-e 's|\](\.\/PERMISSIONS-GUIDE\.md)|](permissions-guide.md)|g' \
|
||||
-e 's|\](\.\/FEATURE-REGENERATION-PROMPTS\.md)|](feature-regeneration-prompts.md)|g' \
|
||||
-e 's|\](\.\/MODULE-IMPLEMENTATION-GUIDE\.md)|](module-implementation-guide.md)|g' \
|
||||
-e 's|\](\.\/MODULE_STATUS\.md)|](module-status.md)|g' \
|
||||
-e 's|\](\.\/LUCI_DEVELOPMENT_REFERENCE\.md)|](luci-development-reference.md)|g' \
|
||||
-e 's|\](\.\.\/TODO-ANALYSE\.md)|](todo-analyse.md)|g' \
|
||||
-e 's|\](\.\/CODEX\.md)|](codex.md)|g' \
|
||||
{} +
|
||||
|
||||
echo ""
|
||||
echo "🏗️ Building site preview..."
|
||||
mkdocs build
|
||||
|
||||
echo ""
|
||||
echo "✅ GitHub Pages setup complete!"
|
||||
echo ""
|
||||
echo "📋 Next steps:"
|
||||
echo ""
|
||||
echo "1️⃣ Test locally:"
|
||||
echo " mkdocs serve"
|
||||
echo " Open: http://127.0.0.1:8000"
|
||||
echo ""
|
||||
echo "2️⃣ Commit and push:"
|
||||
echo " git add mkdocs.yml docs/"
|
||||
echo " git commit -m 'Add GitHub Pages documentation site'"
|
||||
echo " git push"
|
||||
echo ""
|
||||
echo "3️⃣ Enable GitHub Pages in repository settings:"
|
||||
echo " - Go to: https://github.com/gkerma/secubox-openwrt/settings/pages"
|
||||
echo " - Source: Deploy from a branch"
|
||||
echo " - Branch: master"
|
||||
echo " - Folder: /docs"
|
||||
echo " - Save"
|
||||
echo ""
|
||||
echo "4️⃣ Your site will be live at:"
|
||||
echo " https://gkerma.github.io/secubox-openwrt/"
|
||||
echo ""
|
||||
echo "🎉 Done! MkDocs Material theme provides a modern documentation site."
|
||||
332
scripts/setup-wiki.sh
Executable file
332
scripts/setup-wiki.sh
Executable file
@ -0,0 +1,332 @@
|
||||
#!/bin/bash
|
||||
# GitHub Wiki Setup Script
|
||||
# Syncs DOCS/ directory to GitHub Wiki
|
||||
|
||||
set -e
|
||||
|
||||
WIKI_REPO="git@github.com:gkerma/secubox-openwrt.wiki.git"
|
||||
DOCS_DIR="./DOCS"
|
||||
WIKI_DIR="./wiki-temp"
|
||||
|
||||
echo "🔧 SecuBox GitHub Wiki Setup"
|
||||
echo "=============================="
|
||||
echo ""
|
||||
|
||||
# Check if docs directory exists
|
||||
if [ ! -d "$DOCS_DIR" ]; then
|
||||
echo "❌ Error: DOCS directory not found"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Clone wiki repository
|
||||
echo "📥 Cloning wiki repository..."
|
||||
if [ -d "$WIKI_DIR" ]; then
|
||||
rm -rf "$WIKI_DIR"
|
||||
fi
|
||||
|
||||
git clone "$WIKI_REPO" "$WIKI_DIR" 2>/dev/null || {
|
||||
echo "⚠️ Wiki repository doesn't exist yet."
|
||||
echo " Please enable Wiki in GitHub repository settings first:"
|
||||
echo " https://github.com/gkerma/secubox-openwrt/settings"
|
||||
echo ""
|
||||
echo " Then run this script again."
|
||||
exit 1
|
||||
}
|
||||
|
||||
cd "$WIKI_DIR"
|
||||
|
||||
echo "🗑️ Cleaning old wiki content..."
|
||||
# Keep .git directory, remove everything else
|
||||
find . -maxdepth 1 -not -name '.git' -not -name '.' -not -name '..' -exec rm -rf {} +
|
||||
|
||||
echo "📋 Creating wiki structure..."
|
||||
|
||||
# Create Home page (wiki landing page)
|
||||
cat > Home.md << 'EOF'
|
||||
# SecuBox Documentation
|
||||
|
||||
**Version:** 1.0.0
|
||||
**Last Updated:** 2025-12-28
|
||||
**Project:** OpenWrt LuCI Security & Management Suite
|
||||
|
||||
Welcome to the SecuBox documentation wiki! This comprehensive guide covers all aspects of developing, deploying, and maintaining SecuBox modules.
|
||||
|
||||
---
|
||||
|
||||
## 📚 Quick Navigation
|
||||
|
||||
### Getting Started
|
||||
- **[Quick Start Guide](Quick-Start)** - Essential rules and commands for daily development
|
||||
- **[Documentation Index](Documentation-Index)** - Complete guide to all documentation
|
||||
|
||||
### Core Guides
|
||||
- **[Development Guidelines](Development-Guidelines)** - Complete development reference with architecture diagrams
|
||||
- **[Code Templates](Code-Templates)** - Working code examples and patterns
|
||||
- **[Module Implementation](Module-Implementation-Guide)** - Step-by-step implementation workflow
|
||||
|
||||
### Reference
|
||||
- **[RPCD & Architecture](CLAUDE)** - Build system, CI/CD, and critical naming conventions
|
||||
- **[Validation Guide](Validation-Guide)** - Module validation and testing
|
||||
- **[Permissions Guide](Permissions-Guide)** - File permissions reference
|
||||
|
||||
### Module Specifications
|
||||
- **[Feature Regeneration Prompts](Feature-Regeneration-Prompts)** - AI prompts for all 15 modules
|
||||
- **[Module Status](Module-Status)** - Current status of all modules
|
||||
- **[LuCI Development Reference](LuCI-Development-Reference)** - LuCI framework guide
|
||||
|
||||
### Tools & Automation
|
||||
- **[TODO Roadmap](TODO-Analyse)** - Documentation improvement roadmap
|
||||
- **[Archived Documents](archive/)** - Historical and completed documentation
|
||||
|
||||
---
|
||||
|
||||
## 🏗️ Architecture Overview
|
||||
|
||||
SecuBox is a comprehensive security and network management suite for OpenWrt consisting of 15 LuCI application modules:
|
||||
|
||||
### Core Control (2 modules)
|
||||
- **SecuBox Central Hub** - Main dashboard and module management
|
||||
- **System Hub** - System administration (9 tabs: health, services, logs, backup, etc.)
|
||||
|
||||
### Security & Monitoring (2 modules)
|
||||
- **CrowdSec Dashboard** - Intrusion prevention and threat intelligence
|
||||
- **Netdata Dashboard** - Real-time system monitoring
|
||||
|
||||
### Network Intelligence (2 modules)
|
||||
- **Netifyd Dashboard** - Deep packet inspection and classification
|
||||
- **Network Modes** - Network profile management
|
||||
|
||||
### VPN & Access Control (3 modules)
|
||||
- **WireGuard Dashboard** - VPN tunnel management
|
||||
- **Client Guardian** - Network access control and captive portal
|
||||
- **Auth Guardian** - Authentication system
|
||||
|
||||
### Bandwidth & Traffic (2 modules)
|
||||
- **Bandwidth Manager** - QoS and bandwidth quotas
|
||||
- **Traffic Shaper** - Advanced traffic shaping
|
||||
|
||||
### Performance & Services (2 modules)
|
||||
- **CDN Cache** - Content delivery network proxy cache
|
||||
- **VHost Manager** - Virtual host configuration
|
||||
|
||||
### System Optimization (2 modules)
|
||||
- **Media Flow** - Media traffic optimization
|
||||
- **KSM Manager** - Kernel same-page merging
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### For New Contributors
|
||||
1. Start with **[Quick Start Guide](Quick-Start)** - Essential rules and commands
|
||||
2. Read **[Development Guidelines](Development-Guidelines)** - Complete development guide
|
||||
3. Review **[CLAUDE](CLAUDE)** - Build system and architecture
|
||||
|
||||
### For AI-Assisted Development
|
||||
1. Use **[Module Implementation Guide](Module-Implementation-Guide)** - Step-by-step workflow
|
||||
2. Copy prompts from **[Feature Regeneration Prompts](Feature-Regeneration-Prompts)**
|
||||
3. Reference **[Code Templates](Code-Templates)** for implementation patterns
|
||||
|
||||
---
|
||||
|
||||
## 📊 Design System
|
||||
|
||||
SecuBox uses a modern, consistent design system:
|
||||
|
||||
- **Color Palette:** Indigo/Violet gradients with dark mode support
|
||||
- **Typography:** Inter (text) + JetBrains Mono (code/values)
|
||||
- **Components:** Cards, badges, buttons with gradient effects
|
||||
- **Layout:** Responsive grid system (130px, 240px, 300px minimums)
|
||||
|
||||
See **[Development Guidelines - Design System](Development-Guidelines#design-system--ui-guidelines)** for complete specifications.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Development Workflow
|
||||
|
||||
### Critical Rules
|
||||
1. **RPCD Naming:** Script name must match ubus object (`luci.module-name`)
|
||||
2. **Menu Paths:** Must match view file locations exactly
|
||||
3. **Permissions:** 755 for RPCD scripts, 644 for CSS/JS
|
||||
4. **Validation:** Always run `./secubox-tools/validate-modules.sh` before commit
|
||||
|
||||
### Tools
|
||||
- `validate-modules.sh` - 7 automated validation checks
|
||||
- `fix-permissions.sh` - Auto-fix file permissions
|
||||
- `local-build.sh` - Local package building
|
||||
|
||||
---
|
||||
|
||||
## 🌐 Live Demo
|
||||
|
||||
**Production Demo:** https://secubox.cybermood.eu
|
||||
|
||||
- Main dashboard: `/`
|
||||
- System Hub: `/system-hub`
|
||||
- CrowdSec: `/crowdsec`
|
||||
- All 15 modules accessible
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
- **Documentation Issues:** [GitHub Issues](https://github.com/gkerma/secubox-openwrt/issues)
|
||||
- **Technical Support:** support@cybermind.fr
|
||||
- **Company:** CyberMind.fr
|
||||
|
||||
---
|
||||
|
||||
## 📝 License
|
||||
|
||||
Apache-2.0
|
||||
|
||||
---
|
||||
|
||||
**Maintainer:** CyberMind.fr
|
||||
**Last Updated:** 2025-12-28
|
||||
EOF
|
||||
|
||||
# Create sidebar navigation
|
||||
cat > _Sidebar.md << 'EOF'
|
||||
## 📚 Navigation
|
||||
|
||||
### Getting Started
|
||||
* [Home](Home)
|
||||
* [Quick Start](Quick-Start)
|
||||
* [Documentation Index](Documentation-Index)
|
||||
|
||||
### Core Guides
|
||||
* [Development Guidelines](Development-Guidelines)
|
||||
* [Code Templates](Code-Templates)
|
||||
* [Module Implementation](Module-Implementation-Guide)
|
||||
|
||||
### Reference
|
||||
* [RPCD & Architecture](CLAUDE)
|
||||
* [Validation Guide](Validation-Guide)
|
||||
* [Permissions Guide](Permissions-Guide)
|
||||
|
||||
### Specifications
|
||||
* [Feature Prompts](Feature-Regeneration-Prompts)
|
||||
* [Module Status](Module-Status)
|
||||
* [LuCI Reference](LuCI-Development-Reference)
|
||||
|
||||
### Tools
|
||||
* [TODO Roadmap](TODO-Analyse)
|
||||
* [Archive](archive)
|
||||
|
||||
---
|
||||
|
||||
### Quick Links
|
||||
* [GitHub Repo](https://github.com/gkerma/secubox-openwrt)
|
||||
* [Live Demo](https://secubox.cybermood.eu)
|
||||
* [Issues](https://github.com/gkerma/secubox-openwrt/issues)
|
||||
EOF
|
||||
|
||||
echo "📄 Copying documentation files..."
|
||||
|
||||
# Function to convert filename to wiki format
|
||||
convert_filename() {
|
||||
local filename="$1"
|
||||
# Remove .md extension, replace hyphens with spaces for wiki URLs
|
||||
# GitHub wiki uses kebab-case in filenames but displays with spaces
|
||||
echo "${filename%.md}" | sed 's/-/ /g'
|
||||
}
|
||||
|
||||
# Copy main documentation files
|
||||
# GitHub Wiki uses filenames without extensions in links
|
||||
cp "../$DOCS_DIR/QUICK-START.md" "Quick-Start.md"
|
||||
cp "../$DOCS_DIR/DEVELOPMENT-GUIDELINES.md" "Development-Guidelines.md"
|
||||
cp "../$DOCS_DIR/DOCUMENTATION-INDEX.md" "Documentation-Index.md"
|
||||
cp "../$DOCS_DIR/CODE-TEMPLATES.md" "Code-Templates.md"
|
||||
cp "../$DOCS_DIR/CLAUDE.md" "CLAUDE.md"
|
||||
cp "../$DOCS_DIR/VALIDATION-GUIDE.md" "Validation-Guide.md"
|
||||
cp "../$DOCS_DIR/PERMISSIONS-GUIDE.md" "Permissions-Guide.md"
|
||||
cp "../$DOCS_DIR/FEATURE-REGENERATION-PROMPTS.md" "Feature-Regeneration-Prompts.md"
|
||||
cp "../$DOCS_DIR/MODULE-IMPLEMENTATION-GUIDE.md" "Module-Implementation-Guide.md"
|
||||
cp "../$DOCS_DIR/MODULE_STATUS.md" "Module-Status.md"
|
||||
cp "../$DOCS_DIR/LUCI_DEVELOPMENT_REFERENCE.md" "LuCI-Development-Reference.md"
|
||||
cp "../TODO-ANALYSE.md" "TODO-Analyse.md"
|
||||
|
||||
# Create archive index page
|
||||
cat > archive.md << 'EOF'
|
||||
# Documentation Archive
|
||||
|
||||
Historical and completed documentation.
|
||||
|
||||
## Archived Documents
|
||||
|
||||
* [Build Issues](archive/Build-Issues) - Historical build troubleshooting
|
||||
* [Completion Report](archive/Completion-Report) - Project completion milestone
|
||||
* [Module Enable/Disable Design](archive/Module-Enable-Disable-Design) - Feature design document
|
||||
|
||||
See [Archive README](archive/README) for archive policy and details.
|
||||
|
||||
---
|
||||
|
||||
[← Back to Home](Home)
|
||||
EOF
|
||||
|
||||
# Create archive directory and copy files
|
||||
mkdir -p archive
|
||||
cp "../$DOCS_DIR/archive/README.md" "archive/README.md"
|
||||
cp "../$DOCS_DIR/archive/BUILD_ISSUES.md" "archive/Build-Issues.md"
|
||||
cp "../$DOCS_DIR/archive/COMPLETION_REPORT.md" "archive/Completion-Report.md"
|
||||
cp "../$DOCS_DIR/archive/MODULE-ENABLE-DISABLE-DESIGN.md" "archive/Module-Enable-Disable-Design.md"
|
||||
|
||||
echo "🔧 Fixing internal links for wiki format..."
|
||||
# GitHub Wiki uses different link format: [Text](Page-Name) instead of [Text](./file.md)
|
||||
find . -name "*.md" -type f -exec sed -i \
|
||||
-e 's|\](\.\/QUICK-START\.md)|](Quick-Start)|g' \
|
||||
-e 's|\](\.\/DEVELOPMENT-GUIDELINES\.md)|](Development-Guidelines)|g' \
|
||||
-e 's|\](\.\/DOCUMENTATION-INDEX\.md)|](Documentation-Index)|g' \
|
||||
-e 's|\](\.\/CODE-TEMPLATES\.md)|](Code-Templates)|g' \
|
||||
-e 's|\](\.\/CLAUDE\.md)|](CLAUDE)|g' \
|
||||
-e 's|\](\.\/VALIDATION-GUIDE\.md)|](Validation-Guide)|g' \
|
||||
-e 's|\](\.\/PERMISSIONS-GUIDE\.md)|](Permissions-Guide)|g' \
|
||||
-e 's|\](\.\/FEATURE-REGENERATION-PROMPTS\.md)|](Feature-Regeneration-Prompts)|g' \
|
||||
-e 's|\](\.\/MODULE-IMPLEMENTATION-GUIDE\.md)|](Module-Implementation-Guide)|g' \
|
||||
-e 's|\](\.\/MODULE_STATUS\.md)|](Module-Status)|g' \
|
||||
-e 's|\](\.\/LUCI_DEVELOPMENT_REFERENCE\.md)|](LuCI-Development-Reference)|g' \
|
||||
-e 's|\](\.\.\/TODO-ANALYSE\.md)|](TODO-Analyse)|g' \
|
||||
-e 's|\](\.\/CODEX\.md)|](CODEX)|g' \
|
||||
{} +
|
||||
|
||||
echo "📊 Generating wiki statistics..."
|
||||
file_count=$(find . -name "*.md" -type f | wc -l)
|
||||
echo " Total pages: $file_count"
|
||||
|
||||
echo ""
|
||||
echo "💾 Committing changes to wiki..."
|
||||
git add .
|
||||
git commit -m "Sync documentation from DOCS/ directory
|
||||
|
||||
- Updated all documentation files
|
||||
- Added Home page with navigation
|
||||
- Created sidebar for easy navigation
|
||||
- Organized archive section
|
||||
- Fixed internal links for wiki format
|
||||
|
||||
Total pages: $file_count
|
||||
|
||||
🤖 Generated with SecuBox wiki sync script
|
||||
Date: $(date +%Y-%m-%d)
|
||||
"
|
||||
|
||||
echo ""
|
||||
echo "📤 Pushing to GitHub Wiki..."
|
||||
git push origin master
|
||||
|
||||
echo ""
|
||||
echo "✅ Wiki successfully updated!"
|
||||
echo ""
|
||||
echo "🌐 View your wiki at:"
|
||||
echo " https://github.com/gkerma/secubox-openwrt/wiki"
|
||||
echo ""
|
||||
echo "📋 Pages created: $file_count"
|
||||
echo ""
|
||||
|
||||
# Cleanup
|
||||
cd ..
|
||||
rm -rf "$WIKI_DIR"
|
||||
|
||||
echo "🎉 Done! Wiki is live on GitHub."
|
||||
Loading…
Reference in New Issue
Block a user