Wiki.js

---

name: Wiki.js description: Deploy and manage Wiki.js documentation sites avoiding common configuration traps. metadata: {"clawdbot":{"emoji":"📖","os":["linux","darwin","win32"]}}

---

Critical Initial Config

Site URL must be correct from first setup — changing later breaks all internal links, no easy fix

PostgreSQL over SQLite for any multi-user setup — SQLite locks under concurrent writes

HTTPS terminates at reverse proxy — Wiki.js runs HTTP internally, don't configure SSL in Wiki.js

Editor Traps

Visual Editor uses HTML underneath — switching from Markdown loses formatting, can't switch back cleanly

Markdown editor is the safe default — WYSIWYG has rendering quirks and sync issues

Internal links require locale prefix — Link not just /path/to/page

Permission Pitfalls

Deny rules take precedence over allow — overlapping patterns cause unexpected lockouts

Page rules use path patterns — /engineering/* covers subpages, /engineering is exact match only

Default "Users" group applies to all new accounts — configure before inviting users

Storage and Sync

Git sync is one-way by default — Wiki.js to Git only, external edits don't sync back

Asset storage in database bloats backups — use S3/GCS for images on larger wikis

Database backup IS the complete backup — all content, users, permissions stored there

Search Behavior

Search respects permissions — users don't find pages they can't access (can cause confusion)

Search index rebuilds automatically — large imports need patience, no manual trigger helps

Elasticsearch optional — built-in DB search works but lacks relevance ranking

Troubleshooting Specifics

Login redirect loops — almost always HTTPS/HTTP mismatch in Site URL config

Assets not loading — Site URL doesn't match actual access URL

Page shows 404 after creation — special characters in path, use lowercase alphanumeric

Slow after import — search reindexing in progress, wait or check Admin > Utilities