Docs project idea
2026-03-10
After getting slightly frustrated with existing docs tools, i had an idea.
Use composability and the correct level of abstraction to solve this in a hopefully sustainable way.
The basic idea: I like writing my content in plain text files, in a human readable way. Currently markdown seems to be the way of doing that (if you like having some basic styling options). I also like having my content easily available from anywhere, without complicated setups - Websites are great for that.
So our requirements seem pretty simple: Take markdown files, render them in a nice way as websites. This is exactly what i'm currently using Zola for, but there are various good tools available, and if they all die there's still templating tools like Pandoc or others that allow you to solve this with a custom shell script.
I also believe any docs platform should make it frictionless to edit, to encourage keeping the docs up to date. For editing files, i already host notes.shiny.space (behind login) and it's been working great - super simple, no overhead. We should be able to use either that, or a somewhat more fancy solution such as a side by side view of the plain text and what it's rendered as, or even go full WYSIWYG editor with (EasyMDE, Milkdown, likely others). Here we need to make sure that a save triggers a zola build, and consider even adding some sort of version control / change history.
Main efforts to get this working: Templates (plan carefully if you want a hierarchy like bookstack, or prefer flat, or something else entirely), Backend (combine file saving and site rebuilding and edit history in a smart, performant way)