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.

# 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.

# 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:

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.

# 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:

#!/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:

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:

# 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:

<!-- 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:

#!/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:

# 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)

# 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)

{
  "scripts": {
    "sync-wiki": "cp wiki/*.md ../viewer.wiki/ && cd ../viewer.wiki && git add . && git commit -m 'Sync wiki' && git push"
  }
}

Or create a 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:

ssh -T git@git.appmodel.nl

Merge Conflicts

If both local and Gitea wiki are edited:

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