@crownpeak/dqm-react-component-dev-mcp 1.2.0

package/data/WIKI-DEPLOYMENT.md

@@ -0,0 +1,348 @@
+# GitHub Wiki Deployment Guide
+
+Complete guide for deploying and maintaining the Crownpeak DQM React Component documentation wiki.
+
+## Single Source of Truth Architecture
+
+**Key Principle:** Avoid duplication - maintain ONE authoritative source for all documentation.
+
+### Structure
+
+```
+/
+├── README.md                    # GitHub landing page (stays in root)
+├── LICENSE                      # Stays in root
+├── CONTRIBUTING.md             # Stays in root (GitHub feature)
+├── CODE_OF_CONDUCT.md          # Stays in root (GitHub feature)
+│
+├── docs/                       # 📚 SINGLE SOURCE OF TRUTH
+│   ├── QUICKSTART.md
+│   ├── EXAMPLES.md
+│   ├── AUTHENTICATION.md
+│   ├── AI-FEATURES.md
+│   ├── WIDGET-GUIDE.md
+│   ├── MIGRATION-GUIDE.md
+│   ├── API-REFERENCE.md
+│   ├── TROUBLESHOOTING.md
+│   ├── BACKEND-API.md
+│   ├── DEVELOPMENT.md
+│   ├── NPM-PUBLISH.md
+│   ├── REDIS-SETUP.md
+│   └── SERVER.md
+│
+├── wiki/                       # 🔨 BUILD OUTPUT (in .gitignore)
+│   ├── Home.md                 # Template (committed)
+│   ├── _Sidebar.md             # Template (committed)
+│   ├── README.md               # Documentation (committed)
+│   └── *.md                    # Generated files (not committed)
+│
+└── scripts/
+    ├── wiki-build.sh           # Build wiki/ from docs/
+    └── wiki-deploy.sh          # Deploy wiki/ to GitHub Wiki
+```
+
+### Why This Structure?
+
+✅ **No Duplication** - `docs/` is the only source  
+✅ **Version Control** - Docs versioned with code  
+✅ **PR Reviews** - Documentation changes reviewed with code  
+✅ **Developer Access** - Developers have docs locally  
+✅ **Build Automation** - `wiki/` generated automatically  
+✅ **Clean Git History** - Build outputs not committed
+
+### 1. Getting Started (4 pages)
+- **[Home](wiki/Home.md)** - Main landing page with quick start
+- **[Quick-Start](wiki/Quick-Start.md)** - Installation and basic setup
+- **[Examples](wiki/Examples.md)** - 10 integration examples (React, Next.js, AI features)
+- **[Authentication](wiki/Authentication.md)** - Direct API, backend proxy with Mermaid diagrams
+
+### 2. AI Features (4 pages)
+- **[AI-Features](wiki/AI-Features.md)** - Complete AI documentation with 4 Mermaid diagrams
+- **[API-Reference](wiki/API-Reference.md)** - Full TypeScript API (800+ lines)
+- **[Migration-Guide](wiki/Migration-Guide.md)** - v1.0→v1.1 upgrade guide
+- **[Troubleshooting](wiki/Troubleshooting.md)** - FAQ, error codes, debugging (600+ lines)
+
+### 3. Advanced Usage (2 pages)
+- **[Widget-Bundle](wiki/Widget-Bundle.md)** - IIFE/ESM bundles, CMS integrations
+- **[Backend-Server](wiki/Backend-Server.md)** - Backend server setup
+
+### 4. Development (4 pages)
+- **[Development](wiki/Development.md)** - Local development guide
+- **[NPM-Publish](wiki/NPM-Publish.md)** - Publishing workflow
+- **[Contributing](wiki/Contributing.md)** - Contribution guidelines
+- **[Code-of-Conduct](wiki/Code-of-Conduct.md)** - Community guidelines
+
+### Navigation (2 files)
+- **[_Sidebar.md](wiki/_Sidebar.md)** - Manual sidebar navigation
+- **[README.md](wiki/README.md)** - Wiki structure documentation
+
+## File Mapping
+
+| Root File | Wiki File | Description |
+|-----------|-----------|-------------|
+| - | `Home.md` | Wiki home page (derived from README.md) |
+| - | `_Sidebar.md` | Navigation sidebar |
+| `QUICKSTART.md` | `Quick-Start.md` | Getting started guide |
+| `EXAMPLES.md` | `Examples.md` | Integration examples |
+| `AUTHENTICATION.md` | `Authentication.md` | Auth configuration |
+| `AI-FEATURES.md` | `AI-Features.md` | AI features documentation |
+| `WIDGET-GUIDE.md` | `Widget-Bundle.md` | Widget bundle guide |
+| `MIGRATION-GUIDE.md` | `Migration-Guide.md` | Migration guide |
+| `API-REFERENCE.md` | `API-Reference.md` | TypeScript API |
+| `TROUBLESHOOTING.md` | `Troubleshooting.md` | Troubleshooting guide |
+| `BACKEND-API.md` | `Backend-Server.md` | Backend server docs |
+| `DEVELOPMENT.md` | `Development.md` | Development guide |
+| `NPM-PUBLISH.md` | `NPM-Publish.md` | Publishing guide |
+| `CONTRIBUTING.md` | `Contributing.md` | Contributing guide |
+| `CODE_OF_CONDUCT.md` | `Code-of-Conduct.md` | Code of conduct |
+
+## Deployment Methods
+
+### Method 1: Automated Script (Recommended)
+
+```bash
+# Deploy to GitHub Wiki
+./scripts/wiki-deploy.sh "Update AI features documentation"
+```
+
+The script will:
+1. Clone wiki repository (if not exists)
+2. Copy all `wiki/*.md` files
+3. Show git diff
+4. Prompt for confirmation
+5. Commit and push to GitHub Wiki
+
+### Method 2: Manual npm Script
+
+Add to `package.json`:
+
+```json
+{
+  "scripts": {
+    "wiki:update": "cp QUICKSTART.md wiki/Quick-Start.md && cp EXAMPLES.md wiki/Examples.md && cp AUTHENTICATION.md wiki/Authentication.md && cp AI-FEATURES.md wiki/AI-Features.md && cp WIDGET-GUIDE.md wiki/Widget-Bundle.md && cp MIGRATION-GUIDE.md wiki/Migration-Guide.md && cp API-REFERENCE.md wiki/API-Reference.md && cp TROUBLESHOOTING.md wiki/Troubleshooting.md && cp BACKEND-API.md wiki/Backend-Server.md && cp DEVELOPMENT.md wiki/Development.md && cp NPM-PUBLISH.md wiki/NPM-Publish.md && cp CONTRIBUTING.md wiki/Contributing.md && cp CODE_OF_CONDUCT.md wiki/Code-of-Conduct.md",
+    "wiki:fix-links": "cd wiki && sed -i '' 's|\\](\\./QUICKSTART\\.md)|](Quick-Start)|g' *.md && sed -i '' 's|\\](\\./EXAMPLES\\.md)|](Examples)|g' *.md && sed -i '' 's|\\](\\./AUTHENTICATION\\.md)|](Authentication)|g' *.md && sed -i '' 's|\\](\\./AI-FEATURES\\.md)|](AI-Features)|g' *.md && sed -i '' 's|\\](\\./WIDGET-GUIDE\\.md)|](Widget-Bundle)|g' *.md && sed -i '' 's|\\](\\./MIGRATION-GUIDE\\.md)|](Migration-Guide)|g' *.md && sed -i '' 's|\\](\\./API-REFERENCE\\.md)|](API-Reference)|g' *.md && sed -i '' 's|\\](\\./TROUBLESHOOTING\\.md)|](Troubleshooting)|g' *.md && sed -i '' 's|\\](\\./BACKEND-API\\.md)|](Backend-Server)|g' *.md && sed -i '' 's|\\](\\./DEVELOPMENT\\.md)|](Development)|g' *.md && sed -i '' 's|\\](\\./NPM-PUBLISH\\.md)|](NPM-Publish)|g' *.md && sed -i '' 's|\\](\\./CONTRIBUTING\\.md)|](Contributing)|g' *.md && sed -i '' 's|\\](\\./CODE_OF_CONDUCT\\.md)|](Code-of-Conduct)|g' *.md",
+    "wiki:deploy": "npm run wiki:update && npm run wiki:fix-links && ./scripts/wiki-deploy.sh"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm run wiki:deploy
+```
+
+### Method 3: Manual GitHub Upload
+
+1. Go to https://github.com/Crownpeak/dqm-react-component/wiki
+2. Click "New Page" for each file
+3. Copy content from `wiki/*.md` files
+4. Save each page
+
+**Note:** This is tedious for 16 pages - use automated methods instead.
+
+## Link Format Conversion
+
+GitHub Wiki uses special link syntax without file extensions:
+
+**Before (Repository):**
+```markdown
+[Quick Start](./QUICKSTART.md)
+[Examples](./EXAMPLES.md)
+```
+
+**After (Wiki):**
+```markdown
+[Quick Start](Quick-Start)
+[Examples](Examples)
+```
+
+All links in `wiki/*.md` files have been automatically converted.
+
+## Updating Documentation
+
+### Workflow
+
+1. **Edit source files in repository root:**
+   ```bash
+   vim QUICKSTART.md
+   vim AI-FEATURES.md
+   # etc.
+   ```
+
+2. **Update wiki/ directory:**
+   ```bash
+   npm run wiki:update      # Copy files
+   npm run wiki:fix-links   # Fix link format
+   ```
+
+3. **Deploy to GitHub Wiki:**
+   ```bash
+   ./scripts/wiki-deploy.sh "Update quick start guide"
+   ```
+
+### Git Workflow
+
+```bash
+# 1. Make changes to documentation
+vim AI-FEATURES.md
+
+# 2. Update wiki/ directory
+npm run wiki:update
+npm run wiki:fix-links
+
+# 3. Commit to repository (feat/localization branch)
+git add AI-FEATURES.md wiki/AI-Features.md
+git commit -m "docs: update AI features guide"
+git push origin feat/localization
+
+# 4. Deploy to GitHub Wiki
+./scripts/wiki-deploy.sh "Update AI features documentation"
+```
+
+## Wiki vs Repository Documentation
+
+### Keep Both Synchronized
+
+| Location | Purpose | Format | Audience |
+|----------|---------|--------|----------|
+| **Repository Root** (`*.md`) | GitHub README display | Standard markdown with `.md` links | GitHub visitors |
+| **`wiki/` Directory** | Wiki source files | Wiki format (no `.md` in links) | Wiki deployment |
+| **GitHub Wiki** | Live documentation | Rendered wiki pages | Documentation readers |
+
+### Why Keep Root Files?
+
+1. **GitHub README:** Repository visitors see documentation in file browser
+2. **Version Control:** Docs versioned with code (in branches)
+3. **Pull Requests:** Documentation changes reviewed with code
+4. **Offline Access:** Developers have docs locally
+
+### Why Separate wiki/ Directory?
+
+1. **Link Format:** Wiki links don't use file extensions
+2. **File Names:** Wiki uses hyphenated names (Quick-Start.md vs QUICKSTART.md)
+3. **Deployment:** Clean separation between source and wiki deployment
+4. **Automation:** Easy to automate wiki updates
+
+## Mermaid Diagrams
+
+The wiki contains **8 Mermaid diagrams** across 3 files:
+
+### AI-Features.md (4 diagrams)
+1. Translation Flow - OpenAI processing pipeline
+2. Summary Generation Flow - Chunking strategies and fallbacks
+3. Chunking Strategy Decision - Token-based chunking logic
+4. Caching Architecture - IndexedDB + In-Memory caching
+
+### Authentication.md (3 diagrams)
+1. Authentication Flow Overview - Props → localStorage → Backend → Login form
+2. Backend Session Flow (Sequence) - Complete session-based authorization flow
+3. Session Type Flow - Direct vs Backend proxy API calls
+
+### Widget-Bundle.md (1 diagram)
+1. Widget Loading Flow - IIFE/ESM initialization and analysis flow
+
+## Maintenance
+
+### Regular Updates
+
+**After each feature/bugfix:**
+1. Update relevant documentation in repository root
+2. Run `npm run wiki:update && npm run wiki:fix-links`
+3. Deploy with `./scripts/wiki-deploy.sh "Description of changes"`
+
+**After releases (v1.1.0, v1.2.0, etc.):**
+1. Update version numbers in all docs
+2. Update Migration-Guide.md with new breaking changes
+3. Deploy updated wiki
+
+### Monitoring
+
+- **Check Wiki:** https://github.com/Crownpeak/dqm-react-component/wiki
+- **Wiki Analytics:** GitHub Insights → Traffic (if available)
+- **User Feedback:** GitHub Issues/Discussions for documentation requests
+
+## Troubleshooting
+
+### Issue: Links not working in wiki
+
+**Cause:** Links still use `.md` extension
+
+**Solution:**
+```bash
+cd wiki
+npm run wiki:fix-links
+```
+
+### Issue: Wiki deployment script fails
+
+**Cause:** Wiki repository not cloned
+
+**Solution:**
+```bash
+git clone https://github.com/Crownpeak/dqm-react-component.wiki.git
+./scripts/wiki-deploy.sh
+```
+
+### Issue: Mermaid diagrams not rendering
+
+**Cause:** GitHub Wiki might not support Mermaid (depends on GitHub features)
+
+**Solution:** Mermaid is supported in GitHub markdown. If diagrams don't render:
+1. Verify syntax with [Mermaid Live Editor](https://mermaid.live/)
+2. Check for any indentation issues
+3. Ensure code blocks use ` ```mermaid ` (not ` ```markdown `)
+
+### Issue: Missing pages in _Sidebar.md
+
+**Cause:** Some pages listed in _Sidebar.md don't exist yet
+
+**Solution:** These are placeholder pages for future expansion:
+- `AI-Translation-OpenAI.md`
+- `AI-Summary.md`
+- `AI-Caching.md`
+- `Internationalization.md`
+- `Custom-Translations.md`
+- `Language-Support.md`
+- `Component-DQMSidebar.md`
+- `Component-ErrorBoundary.md`
+- `Component-Configuration.md`
+- `Widget-IIFE.md`
+- `Widget-ESM.md`
+- `Widget-CMS-Integrations.md`
+- `Hooks-AI.md`
+- `Hooks-Core.md`
+- `Redux-Store.md`
+- `Error-Messages.md`
+- `LocalStorage-Keys.md`
+- `Browser-Compatibility.md`
+- `TypeScript-Types.md`
+- `Performance.md`
+
+You can either:
+1. Remove these links from `_Sidebar.md`
+2. Create these pages by extracting content from existing docs
+3. Leave as-is (GitHub Wiki shows broken links, but it's clear they're placeholders)
+
+## Statistics
+
+- **Total Pages:** 16 (+ 19 placeholders in sidebar)
+- **Total Lines:** ~4,500+ lines of documentation
+- **Mermaid Diagrams:** 8
+- **Code Examples:** 60+
+- **Languages Covered:** TypeScript, JavaScript, HTML, PHP, Liquid, Bash, JSON
+- **Sections:** Getting Started, AI Features, Advanced Usage, Development, Reference
+
+## Next Steps
+
+1. **Create Placeholder Pages:** Extract detailed pages from existing documentation
+2. **Add Screenshots:** Add visual examples to wiki pages
+3. **Video Tutorials:** Embed YouTube videos in wiki
+4. **Community Contributions:** Encourage users to improve documentation via wiki edits
+5. **Translations:** Consider translating wiki to German/Spanish (matching i18n support)
+
+## Resources
+
+- **GitHub Wiki Docs:** https://docs.github.com/en/communities/documenting-your-project-with-wikis
+- **Mermaid Syntax:** https://mermaid.js.org/
+- **Markdown Guide:** https://guides.github.com/features/mastering-markdown/