Goodbye Logseq, Obsidian, and Vimwiki. Hello, mdBook!

I have bounced around numerous note-taking applications, including Obsidian, Logseq, and Vimwiki. Each of them has had at least one fatal flaw that pushed me away from using it. For Logseq, it was the outliner methodology instead of just a standard page. For Obsidian it was the almost complete vim integration but that didn’t quite have everything. For Vimwiki, it was being able to read the notes on mobile. I sought a solution that would check all of these boxes.

I began thinking, “what if I just made a documentation site?”. Sure, there may be 5% of notes that I would be unable to write since they contained sensitive information or something personal, but the other 95% of the notes I took were completely fine to be made public, and may even help others. I have used material for mkdocs before, but wanted to try something new. mdBook, written in rust, fit the bill. I could install with cargo, and then get up and running with a simple mdbook serve for development, and an mdbook build when I was ready to share. This allows me to edit and write my notes using neovim, read them on the go by just going to the webpage, and use the full page notes format.

Getting mdBook setup was a piece of cake. I have outlined the exact steps in a note, but it basically boils down to a cargo install, and then just writing markdown files, outlining the table of contents structure in a single SUMMARY.md file. Configuration options are all done in .toml, and the only big change I ended up making was making it catppuccin themed through mdbook-catppuccin

The next objective that I wanted to try was to get this all running out of codeberg. I recently became a member of Codeberg e.V. and am therefore trying to use the service more. Unfortunately, vercel doesn’t allow you to use a git host outside of GitHub, GitLab or Bickbucket (at least, as far as I could tell based on messing around with it), and so I ended up just mirroring the codeberg repository into a github repo and then setting up vercel as normal. The mirroring process was quite easy to setup, especially with github’s new personalized access tokens that have customizable scope. The process now looks something like this:

local edits -> mdbook build -> git push (codeberg) -> mirror to github -> vercel publishes

Because the contents of the book directory (the result of mdbook build) are just html, css and javascript files, it is a very simple static website, and builds almost instantly. There is no framework to worry about. In the future, I want to try to make codeberg work on its own using woodpecker, codeberg pages, and following this guide, and will write a follow-up post if I end up getting it working.

To see what the code for this new notes site looks like, you can go to the codeberg repo. If you want to take a look at the notes, they are found here