MkDocs VS BookStack

In simple terms, Material for MkDocs is a theme for MkDocs, which is a static site generator specifically designed for project documentation. Think of MkDocs as a tool that converts markdown files into a neat website and the Material theme makes that website look great, inspired by Google’s Material Design principles.

# Welcome to MkDocs For full documentation visit [mkdocs.org](https://www.mkdocs.org). ## Commands * `mkdocs new [dir-name]` - Create a new project. * `mkdocs serve` - Start the live-reloading docs server. * `mkdocs build` - Build the documentation site. * `mkdocs -h` - Print help message and exit. ## Project layout mkdocs.yml # The configuration file. docs/ index.md # The documentation homepage. ... # Other markdown pages, images and other files.

The documentation is built with MkDocs and hosted on GitHub Pages. You can browse the complete documentation at carpet.jerolba.com.

MkDocs

MkDocs is a static site generator designed specifically for project documentation and written in Python. It’s easy to set up, uses markdown for content, and features a number of themes, including the popular Material for MkDocs. MkDocs integrates well with Python-based workflows and CI/CD tools. It’s a great choice for Python developers and teams looking for simplicity and readability.

Because of my frustrations, I've released two example GitHub repositories for two popular static site generators: MkDocs and Sphinx. The goal with these repositories is to be focussed on a minimal project using the static site generator, that builds into a Read The Docs theme compatible website, and provide supporting tooling regarding formatting of the underlying formatting language. It also provides the tooling needed to deploy to GitHub Pages both from the command line and via GitHub Actions (both are powered by the ghp-import project).

The documentation of the CLI is provided via a GitHub page as part of the repository. We are using MkDocs to generate the content, but I think most of the tools in that area are well integrated with GitHub and GitHub Actions.

The original mkdocs uses a Python package for its installer, so you can just pip install mkdocs, mkdocs new ., and then mkdocs build to convert markdown files into HTML.

If you don't like to run javascript outside of a browser, MkDocs is a great Python-based alternative: https://www.mkdocs.org/

I like Markdown because it's simple and doesn't give me that many headaches.

You know what I don't like? HTML, for user submitted content in particular. The mess I've seen, after someone opted for using HTML for messages in a system, because that's what JS based editors were available for at the time. Endless need to work against XSS, with more and more incremental updates needed to the sanitization logic, some of which broke the presentation of the data in the DB.

Never again. Markdown, BBCode, anything but that.

As for docs? Currently just some Markdown, because that's what GitHub, GitLab, Gitea and others all know how to render.

Maybe something like https://www.mkdocs.org/ for the more standalone use cases.

We use outline (https://github.com/outline/outline) at work and it works pretty well for us. It supports collaborative editing, which was the main reason we went with it.

Personally, I use bookstack (https://github.com/BookStackApp/BookStack) at home. Mostly because I really like the mental model of using Bookshelves, Books, Chapters and Pages to sort my notes in.

Additionally at some point people behind this product decided to change the licensing model, and allow the use of community editions for up to 5 nodes. It wasn't my case, but that pushed me to use something more independent. So I started using dockge, then added another service for docker logs, version monitor, and keeps adding applications that are fun to use, for example homebox or bookstack. It was fun until I released the cost of energy and maintenance effort need to keep it running, at my home. Every internet issue, or power issue takes my setup down. Maybe it was not happening very often, but when I wasn’t home, and the hardware was down, there was no chance to fix it remotely. And I started relaying on that service. That is why I simply decided to migrate to hetzner, and podman at the same time, and use remote NFS. However, let's start from the beginning.

BookStack: A platform for storing and organising information and documentation.

Joplin open-source tool, with paid Sync service. However, it supports WebDav sync. As a user of Fastmail have a lot lot of storage for it. Those parts work great, links, complexity level, and clear Markdown. Themes, mobile app, tags, everything I needed was there. Unfortunately, again, for short notes, my go-to app becomes memos, for long-form BookStack, seems to be the best solution. Why? Firstly my love for self-hosted solutions boomed, also Joplin even if looks perfect for my use case was some reason hard to describe and did not encourage me to write. Soo.. I back to Obsidian.

We use Bookstack[0] for this and I can recommend it. Free and open source.

[0] https://www.bookstackapp.com/

Link | Demo | Github | License

While I haven't used it, Bookstack is spoken of favourably.

On another topic, anyone knows anything similar to what's mentioned in this issue? https://github.com/BookStackApp/BookStack/issues/473