Hosting Wiki.js on my FreeBSD server

Notes are indeed crucial tools for organization and personal knowledge management, and their value multiplies exponentially when collaboration enters the picture. Recognizing this fundamental shift in utility, I’ve made the decisive move to migrate from Logseq, a capable but solo-focused note-taking application, to hosting WikiJS on my FreeBSD server.

This transition represents more than just a change in software, it’s an evolution in my approach to knowledge management, prioritizing collaboration and sharing.

By leveraging the capabilities of WikiJS within my self-hosted FreeBSD environment, I’m creating an infrastructure that will maintains control over my data while opening new avenues for collaborative thinking and documentation.

Another reason for the change is that I’ve ended up no longer using Logeseq but rather just use my favorite editor, Neovim and sync with Nextcloud. WikiJS would allow me to use Neovim by using the git storage, while providing an interface for collaboration.

When Wiki.js and Git Don’t Play Nice

Before setting it all up in my server, I’ve tested what I wanted: editing from git storage. Turns out it worked decently, so I’ve set it on the server and imported my Logseq notes, using bash script to format everything properly.

The Frustrating Problem

Recently, I encountered a perplexing issue with my Wiki.js installation connected to a Git backend. Despite trying various sync options from the admin page including “Update All” and other sync features, changes weren’t syncing properly between my Git repository and Wiki.js instance.

The Drastic Solution (That I Didn’t Need)

After exhausting the soft troubleshooting steps, I took the nuclear option: completely erasing my Wiki.js database and starting over. This was time-consuming and did not solve the problem.

Only after this drastic step did I discover the actual culprit: spaces in my filenames.

If I had identified this issue earlier, I could have avoided resetting the database entirely. This simple character issue was preventing proper synchronization between my Git repository and Wiki.js.

Best Practices to Avoid This Issue

To prevent similar problems with Wiki.js and Git integration:

1. Never use spaces in filenames or folder names - Use hyphens or underscores instead
2. Establish clear naming conventions before populating your wiki
3. Make structural changes through the Wiki.js interface rather than directly in Git
4. Regularly back up your database before trying major sync operations

Lesson Learned

The Wiki.js and Git integration offers powerful documentation capabilities, but it comes with some quirks that require attention to detail. Something as seemingly minor as a space character in filenames can lead to significant synchronization issues.

If you’re experiencing sync problems with your Wiki.js installation, check your filenames for spaces before taking drastic measures like resetting your database. A small filename change might save you hours of reconstruction work.