viewer/wiki/WIKI_INTEGRATION.md

# Gitea Wiki Integration Guide

This guide explains how to integrate the local `wiki/` folder with Gitea's wiki system.

## How Gitea Wikis Work

Gitea stores wiki pages in a **separate Git repository** with the naming pattern:
```
<repository>.wiki.git
```

For the `viewer` repository:
- Main repo: `git@git.appmodel.nl:Tour/viewer.git`
- Wiki repo: `git@git.appmodel.nl:Tour/viewer.wiki.git`

Wiki pages are **markdown files** (`.md`) stored in the root of the wiki repository.

## Integration Options

### Option 1: Push Local Wiki to Gitea (Recommended)

This approach replaces the current Gitea wiki with your local content.

```bash
# 1. Clone the Gitea wiki repository
git clone git@git.appmodel.nl:Tour/viewer.wiki.git viewer-wiki

# 2. Copy your wiki files to the wiki repository
cd viewer-wiki
cp ../viewer/wiki/*.md .

# 3. Commit and push
git add .
git commit -m "Initialize wiki with documentation"
git push origin master

# 4. View on Gitea
# Navigate to: https://git.appmodel.nl/Tour/viewer/wiki
```

### Option 2: Use Git Submodule (Bidirectional Sync)

Keep the wiki as a submodule in the main repository for easy synchronization.

```bash
# In the main viewer repository
cd /c/vibe/viewer

# Remove local wiki folder
rm -rf wiki/

# Add Gitea wiki as submodule
git submodule add git@git.appmodel.nl:Tour/viewer.wiki.git wiki

# Copy your documentation
cp ../temp-wiki-backup/*.md wiki/

# Commit to wiki submodule
cd wiki
git add .
git commit -m "Add documentation"
git push origin master

# Update main repository
cd ..
git add wiki
git commit -m "Add wiki as submodule"
git push origin main
```

Now changes can be made either:
- **In Gitea UI**: Edit wiki pages directly
- **Locally**: Edit in `wiki/` folder, commit, and push

To sync changes from Gitea:
```bash
cd wiki
git pull origin master
cd ..
git add wiki
git commit -m "Update wiki submodule"
git push
```

### Option 3: Git Subtree (Advanced)

Similar to submodule but integrates the wiki history into the main repository.

```bash
# Add wiki as subtree
git subtree add --prefix=wiki git@git.appmodel.nl:Tour/viewer.wiki.git master --squash

# Push changes to wiki
git subtree push --prefix=wiki git@git.appmodel.nl:Tour/viewer.wiki.git master

# Pull changes from wiki
git subtree pull --prefix=wiki git@git.appmodel.nl:Tour/viewer.wiki.git master --squash
```

### Option 4: Automated Sync Script

Create a script to automatically sync wiki changes.

Create `sync-wiki.sh`:
```bash
#!/bin/bash
# sync-wiki.sh - Sync local wiki with Gitea

WIKI_REPO="git@git.appmodel.nl:Tour/viewer.wiki.git"
WIKI_DIR="wiki"
TEMP_WIKI="/tmp/gitea-wiki-$$"

# Clone Gitea wiki
git clone "$WIKI_REPO" "$TEMP_WIKI"

# Copy local changes to temp wiki
cp -r "$WIKI_DIR"/*.md "$TEMP_WIKI/"

# Commit and push
cd "$TEMP_WIKI"
git add .
if git diff-staged --quiet; then
  echo "No changes to sync"
else
  git commit -m "Sync wiki from main repository"
  git push origin master
  echo "Wiki synced successfully"
fi

# Cleanup
cd -
rm -rf "$TEMP_WIKI"
```

Usage:
```bash
chmod +x sync-wiki.sh
./sync-wiki.sh
```

## Recommended Workflow

For your deployment pipeline, I recommend **Option 1** with a manual push:

### Step-by-Step Setup

1. **Create wiki repository on Gitea** (if not exists):
   - Go to: https://git.appmodel.nl/Tour/viewer
   - Click "Wiki" tab
   - Create first page (triggers wiki repo creation)

2. **Push local wiki content**:
```bash
# Clone wiki repository
cd /c/vibe
git clone git@git.appmodel.nl:Tour/viewer.wiki.git

# Copy your wiki files
cd viewer.wiki
cp ../viewer/wiki/*.md .

# Verify files
ls -la

# Commit and push
git add .
git commit -m "Initialize wiki documentation

Added:
- Home.md: Main documentation page
- Quick-Start.md: Quick start guide
"
git push origin master
```

3. **Verify on Gitea**:
   - Navigate to: https://git.appmodel.nl/Tour/viewer/wiki
   - You should see your wiki pages

4. **Keep local wiki in main repo** (optional):
   - Keep `wiki/` folder in main repo as "source of truth"
   - When updating wiki, manually sync to Gitea wiki repo
   - Or set up automated sync via CI/CD

## Wiki Page Naming

Gitea wikis follow these conventions:

| Filename | URL | Purpose |
|----------|-----|---------|
| `Home.md` | `/wiki/` or `/wiki/Home` | Main wiki page |
| `Quick-Start.md` | `/wiki/Quick-Start` | Quick start guide |
| `API-Reference.md` | `/wiki/API-Reference` | API documentation |

**Rules**:
- Use PascalCase or kebab-case for multi-word pages
- Spaces in filenames become hyphens in URLs
- First page is always `Home.md`

## Linking Between Pages

In your markdown files:

```markdown
<!-- Link to another wiki page -->
[Quick Start Guide](Quick-Start)

<!-- Link with custom text -->
[Get Started](Quick-Start)

<!-- Link to main repository -->
[View Code](../)

<!-- Link to specific file -->
[Dockerfile](../src/master/Dockerfile)

<!-- External link -->
[Diagrams Library](https://diagrams.mingrammer.com/)
```

## Automation with Post-Receive Hook

To automatically sync wiki on deployment, add to Gitea post-receive hook:

```bash
#!/usr/bin/env bash

# Deploy main app
/usr/local/bin/app-deploy viewer

# Sync wiki (if wiki/ folder exists in repo)
if [ -d "/opt/apps/viewer/wiki" ]; then
  cd /tmp
  git clone git@git.appmodel.nl:Tour/viewer.wiki.git gitea-wiki-$$
  cp /opt/apps/viewer/wiki/*.md /tmp/gitea-wiki-$$/
  cd /tmp/gitea-wiki-$$
  git add .
  if ! git diff --staged --quiet; then
    git commit -m "Auto-sync from main repository"
    git push origin master
  fi
  cd /tmp
  rm -rf /tmp/gitea-wiki-$$
fi
```

## Current Setup Instructions

Based on your current setup, here's what to do:

```bash
# 1. Navigate to your viewer project
cd /c/vibe/viewer

# 2. Clone the wiki repository (for viewer, adjust as needed)
cd ..
git clone git@git.appmodel.nl:Tour/viewer.wiki.git

# 3. Copy wiki files
cp viewer/wiki/*.md viewer.wiki/

# 4. Push to Gitea
cd viewer.wiki
git add .
git commit -m "Initialize wiki with deployment documentation"
git push origin master

# 5. Verify
# Open: https://git.appmodel.nl/Tour/viewer/wiki
```

## Maintaining Both Wikis

If you want to keep both local and Gitea wikis in sync:

### Manual Sync (Simple)
```bash
# After editing local wiki files
cd /c/vibe/viewer/wiki
cp *.md /c/vibe/viewer.wiki/
cd /c/vibe/viewer.wiki
git add .
git commit -m "Update documentation"
git push
```

### Automated Sync (Add to package.json or Makefile)
```json
{
  "scripts": {
    "sync-wiki": "cp wiki/*.md ../viewer.wiki/ && cd ../viewer.wiki && git add . && git commit -m 'Sync wiki' && git push"
  }
}
```

Or create a `Makefile`:
```makefile
.PHONY: sync-wiki

sync-wiki:
	@echo "Syncing wiki to Gitea..."
	@cp wiki/*.md ../viewer.wiki/
	@cd ../viewer.wiki && git add . && git commit -m "Sync wiki from main repo" && git push
	@echo "Wiki synced successfully!"
```

Usage: `make sync-wiki`

## Best Practices

1. **Single Source of Truth**: Choose one location (local or Gitea) as authoritative
2. **Version Control**: Keep wiki changes in Git history
3. **Review Process**: Use pull requests for significant documentation changes
4. **Link Checking**: Regularly verify internal links work
5. **Consistent Formatting**: Use markdown linting tools
6. **Table of Contents**: Keep `Home.md` as navigation hub

## Troubleshooting

### Wiki Repository Doesn't Exist

Create the wiki first in Gitea UI:
1. Go to repository: https://git.appmodel.nl/Tour/viewer
2. Click "Wiki" tab
3. Click "Create New Page"
4. Create a dummy page (will be overwritten)
5. Now you can clone `viewer.wiki.git`

### Permission Denied

Ensure your SSH key is added to Gitea:
```bash
ssh -T git@git.appmodel.nl
```

### Merge Conflicts

If both local and Gitea wiki are edited:
```bash
cd viewer.wiki
git pull origin master
# Resolve conflicts manually
git add .
git commit -m "Merge local and remote changes"
git push
```

## Summary

**Recommended approach for your setup**:

1. Keep `wiki/` in main repository for version control
2. Manually push to Gitea wiki repository when documentation is ready
3. Optionally add automated sync in post-receive hook
4. Edit wiki locally, sync to Gitea for visibility

This gives you the best of both worlds:
- ✅ Documentation versioned with code
- ✅ Visible wiki in Gitea UI
- ✅ Easy to maintain and update
- ✅ Works with existing deployment pipeline