2.2 KiB

Raw Permalink Blame History

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)

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:

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

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

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

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

2.2 KiB Raw Permalink Blame History