106 lines
2.2 KiB
Markdown
106 lines
2.2 KiB
Markdown
# Wiki as Git Repository
|
|
|
|
Gitea wikis are backed by bare git repos at `<repo-url>.wiki.git`. Instead of using the API (base64 encoding, one page at a time), we clone the wiki repo as a project subfolder and work with plain markdown files.
|
|
|
|
## Wiki directory
|
|
|
|
The wiki is cloned into `.wiki/` at the project root:
|
|
|
|
```
|
|
project-root/
|
|
├── .claude/.env
|
|
├── .wiki/ ← wiki git repo
|
|
│ ├── Home.md
|
|
│ ├── feature-12-user-auth.md
|
|
│ ├── feature-12-user-auth-t01.md
|
|
│ └── ...
|
|
└── src/
|
|
```
|
|
|
|
## Setup (once per project)
|
|
|
|
```bash
|
|
set -a; source .claude/.env; set +a
|
|
|
|
WIKI_URL="https://${GITEA_USER}:${GITEA_ACCESS_TOKEN}@${GITEA_HOST#https://}/${owner}/${repo}.wiki.git"
|
|
|
|
if [ -d .wiki/.git ]; then
|
|
git -C .wiki pull --rebase
|
|
else
|
|
git clone "$WIKI_URL" .wiki
|
|
fi
|
|
```
|
|
|
|
If the wiki repo doesn't exist yet (first wiki page), initialize it:
|
|
|
|
```bash
|
|
mkdir -p .wiki && cd .wiki
|
|
git init
|
|
git remote add origin "$WIKI_URL"
|
|
echo "# Wiki" > Home.md
|
|
git add Home.md
|
|
git commit -m "init wiki"
|
|
git push -u origin main
|
|
```
|
|
|
|
## Writing pages
|
|
|
|
Just write markdown files in `.wiki/`:
|
|
|
|
```bash
|
|
# Write a page (filename = page name on Gitea)
|
|
cat > .wiki/feature-12-user-auth.md << 'EOF'
|
|
# User Authentication
|
|
...
|
|
EOF
|
|
```
|
|
|
|
Page naming rules:
|
|
- Filename (without `.md`) = wiki page name
|
|
- Use kebab-case: `feature-12-user-auth.md`
|
|
- Sub-tasks: `feature-12-user-auth-t01.md`
|
|
- Home/index: `Home.md`
|
|
|
|
## Publishing
|
|
|
|
After writing all pages, commit and push in one go:
|
|
|
|
```bash
|
|
cd .wiki
|
|
git add -A
|
|
git commit -m "feat(wiki): publish plan for issue #12"
|
|
git push
|
|
```
|
|
|
|
This is atomic — all pages appear at once, unlike the API approach.
|
|
|
|
## Reading pages
|
|
|
|
Just read files from `.wiki/`:
|
|
|
|
```bash
|
|
cat .wiki/feature-12-user-auth.md
|
|
```
|
|
|
|
## Wiki URL construction
|
|
|
|
Page URLs on Gitea: `https://$GITEA_HOST/$owner/$repo/wiki/$page-name`
|
|
|
|
Where `$page-name` is the filename without `.md`.
|
|
|
|
## .gitignore
|
|
|
|
Add `.wiki/` to the project's `.gitignore` — it's a separate repo, not part of the main project:
|
|
|
|
```
|
|
.wiki/
|
|
```
|
|
|
|
## Advantages over API
|
|
|
|
- No base64 encoding
|
|
- Write multiple pages, publish atomically
|
|
- Read/edit pages with standard file tools (Read, Edit, Write)
|
|
- Full git history for wiki changes
|
|
- Works offline, push when ready
|