Add wiki as submodule
This commit is contained in:
361
WIKI_INTEGRATION.md
Normal file
361
WIKI_INTEGRATION.md
Normal file
@@ -0,0 +1,361 @@
|
||||
# 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/diagram.wiki.git diagram-wiki
|
||||
|
||||
# 2. Copy your wiki files to the wiki repository
|
||||
cd diagram-wiki
|
||||
cp ../diagram/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/diagram/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 diagram repository
|
||||
cd /c/vibe/diagram
|
||||
|
||||
# Remove local wiki folder
|
||||
rm -rf wiki/
|
||||
|
||||
# Add Gitea wiki as submodule
|
||||
git submodule add git@git.appmodel.nl:Tour/diagram.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/diagram.wiki.git master --squash
|
||||
|
||||
# Push changes to wiki
|
||||
git subtree push --prefix=wiki git@git.appmodel.nl:Tour/diagram.wiki.git master
|
||||
|
||||
# Pull changes from wiki
|
||||
git subtree pull --prefix=wiki git@git.appmodel.nl:Tour/diagram.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/diagram.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/diagram
|
||||
- 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/diagram.wiki.git
|
||||
|
||||
# Copy your wiki files
|
||||
cd diagram.wiki
|
||||
cp ../diagram/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/diagram/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 diagram
|
||||
|
||||
# Sync wiki (if wiki/ folder exists in repo)
|
||||
if [ -d "/opt/apps/diagram/wiki" ]; then
|
||||
cd /tmp
|
||||
git clone git@git.appmodel.nl:Tour/diagram.wiki.git gitea-wiki-$$
|
||||
cp /opt/apps/diagram/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 diagram project
|
||||
cd /c/vibe/diagram
|
||||
|
||||
# 2. Clone the wiki repository (for viewer, adjust as needed)
|
||||
cd ..
|
||||
git clone git@git.appmodel.nl:Tour/diagram.wiki.git
|
||||
|
||||
# 3. Copy wiki files
|
||||
cp diagram/wiki/*.md diagram.wiki/
|
||||
|
||||
# 4. Push to Gitea
|
||||
cd diagram.wiki
|
||||
git add .
|
||||
git commit -m "Initialize wiki with deployment documentation"
|
||||
git push origin master
|
||||
|
||||
# 5. Verify
|
||||
# Open: https://git.appmodel.nl/Tour/diagram/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/diagram/wiki
|
||||
cp *.md /c/vibe/diagram.wiki/
|
||||
cd /c/vibe/diagram.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 ../diagram.wiki/ && cd ../diagram.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 ../diagram.wiki/
|
||||
@cd ../diagram.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/diagram
|
||||
2. Click "Wiki" tab
|
||||
3. Click "Create New Page"
|
||||
4. Create a dummy page (will be overwritten)
|
||||
5. Now you can clone `diagram.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 diagram.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
|
||||
Reference in New Issue
Block a user