Otter Wiki: A minimalistic wiki powered by Python, Markdown and git | Hacker News Reader

Otter Wiki: A minimalistic wiki powered by Python, Markdown and git

otterwiki.com

222 pointsthunderbong62 comments

Not many wiki site engines based on Markdown work directly from git as cleanly as this.

There's a few of them though, such as this old Ruby lang standby with a decade's worth of features that a decade ago was a way to host your same GitHub Pages site locally, supporting SSO:

https://github.com/gollum/gollum

https://github.com/gollum/gollum/wiki/Gollum-via-Rack-and-CA...

https://tina.io/ tinacms is very modern & well built, git markdown typescript. and headless or with template components.

it's such an epic feat, how programmers have grown up to manage source over time & changes. i very much hope this richness cam extend beyond code some day, stop being arbitrary UI we craft & become good data structures that transcend each application.

An even older one is my gitit, started in 2008!

https://hackage.haskell.org/package/gitit-0.15.1.2

It doesn't limit itself to markdown, nor to git (you can use darcs, hg, or even sqlite). A bit long in the tooth, though -- I stopped working on it once spam started to make self-hosted public wikis untenable.

Ikiwiki is nice. It's also a static wiki compiler and tries very hard to minimize the amount of rebuilding for each edit.

I really enjoyed Gollum for awhile, but I'm not a Rubyist, and past a certain point, every time I tried to run it or Jekyll I got dependency problems that I'd eventually solve, but without understanding. It was undoubtedly user error; I should definitely have learned and used rvm or something.

It should be noted that goolum is AFAIK still the backend behind GitLabs Wikis. It works quite well Ime and was easy to setup/use for basic Markdown Documents.

We actually switched from Gollum to OtterWiki!

gitlab wikis — separate repos to the main project repo that folks can clone/edit/push just like any repo.

personally i prefer confluence though. just find it faster to dump things out.

Wikmd is another git / markdown / plain text file storage wiki.

https://github.com/Linbreux/wikmd

I can’t remember why I switched from gollum to wikmd. I suspect installed size might be why.

> First of all, there are no otters here. I'm utterly sorry about that.

incredibly important suggestion: replace "utterly" with "otterly"

did you miss the part there are no otter?

My definition of minimalistic is a SSG where you use Github's WYSIWYG editor and push changes to trigger a pipeline that rebuilds the page and uploads it to a cloud service with S3 support.

Involving GitHub and setting up its actions is only minimalist from a very particular point of view.

Well, in real life this setup uses Gitlab but I referenced Github because I assumed they have better WYSIWYG options than Gitlab.

And why that matters is because I can run the pipeline from my own laptop with gitlab-runner.

But we all have our own view of minimalistic and mine is "the less code is running, the more minimalistic it is". To be abundantly clear, the less code is running that I have to operate or maintain. Obviously Github, S3 and a SSG generator is a lot of code.

If you're really going for "minimalistic", why not ignore the whole build/SSG and just directly link to a markdown file inside a github repository?

I was literally building my own version of this with madness this morning to go from Obsidian to web in my workflow. Thanks for speeding things up for me. Great work!

It's minimalist until you read the installation part...

As a backend SQL guy I always feel overwhelmed by "minimalist" software that actually depend on me knowing ho to deploy safely on docker or mastering N dependencies before actually having something to try. Long are gone the lamp days... they had their own set of problems (wrong versions!) but it was a simpler time where you felt a little bit more in control.

Old man yell at the clouds I guess...

I often feel the same way. I had someone ask me to make a microservice on some platform she built. I was told it would take 10 minutes. In reality, it took a couple weeks, and then every week for a year I was getting told something was changing and I had to mess with this or that, and also attend daily meetings about the project. 10 minutes turned into 30% of my whole year. The whole platform she built lasted maybe 2 years before it was decided we needed to move on from it. It was a total waste of time.

Meanwhile, I have a little LAMP project that is used significantly more than the micro service, that I’ve run for 15 years that I only have to touch when it needs feature updates. The platform itself just works. Occasionally I’ll need to move to a newer OS, which takes a few hours to get the new server built, run the job to configure it (doing it manually doesn’t take too much longer), then submit a request to change the load balancer to point to the new servers.

Granted, some of this comes down to experience. However, needing to know all the tools involved for the microservice was much more annoying and they broke half the time.

Boring technology just works. That's why it is boring and not appealing to younger developers.

https://boringtechnology.club/

people forget that you need a huge ranch, and several farm hands etc to handle cattle.

while everyone can care for pets with little effort.

That's another subject altogether. Huge ranch tools makers don't advertise their solutions as "simple".

They usually don't advertise at all to the general public because they are b2b oriented.

I got it running locally like this, using uv to manage dependencies:

    git clone https://github.com/redimp/otterwiki.git
    cd otterwiki

    mkdir -p app-data/repository
    git init app-data/repository

    echo "REPOSITORY='${PWD}/app-data/repository'" >> settings.cfg
    echo "SQLALCHEMY_DATABASE_URI='sqlite:///${PWD}/app-data/db.sqlite'" >> settings.cfg
    echo "SECRET_KEY='$(echo $RANDOM | md5sum | head -c 16)'" >> settings.cfg

    export OTTERWIKI_SETTINGS=$PWD/settings.cfg
    uv run --with gunicorn gunicorn --bind 127.0.0.1:8080 otterwiki.server:app

I filed an issue here suggesting that for the docs https://github.com/redimp/otterwiki/issues/146 - and also that it would be great if getting started could be as simple as this:

    pip install otterwiki
    otterwiki \
      --repository app-data/repository \
      --sqlite app-data/db.sqlite \
      --secret-key secret1 \
      --port 8080

And to think people used to think

  ./configure —-prefix=/home/user/appname
  make
  make install

was too complicated

The problems was mainly that even "apt-get build-dep" is not enough to handle all the problems that arise from that. Even if configure was standardized, there was always problems with diversity in systems.

The NIH syndrome is still big in software build tools, everything is complicated unless you have written it yourself in your environment. Admitted I seldom run those commands manually anymore, but things have gotten way worse when I do try. Specific versions of tools, libraries and kernels, or just kernels. Nix build scripts are actually one of the worst offenders here often ignoring every other standard available. Not saying it is bad, just an example of why what you write above is more complicated than it sounds.

I got it to work under Piku (https://piku.github.io) in much the same way (since I support uwsgi, that bit was trivial).

I did have to hardcode the data path, and I think having some form of export/snapshot would help as well, but submitting a patch might be a fun weekend project.

But deploying on Docker is simpler than LAMP! All dependencies included. All binaries included. You can even just tell systemd run it (also usually included).

Its comprehensive. It is not complex. They just show all of the typical ways one would want to deploy.

I can't see any issue with what's in the installation part. It all looks very straightforward for _each_ installation method.

Yeah I’m with you. I cannot stand having to jump through hoop after hoop just to get started - things to download, command line utils to install, line after line after line to copy into the terminal, layers and layers of dependencies, possibly with version incompatibilities that the “getting started” page was never updated to reflect… it’s a nightmare.

Sometimes you just want to sit down and write code and see it working.

come on, you just need to teach a bit of git/k8s/docker/tls/proxies/storage/vault/markdown/linux/apt and then your family will be autonomous at managing this wiki IF you are allowed to take vacations.

Huh! This is really nice! If I had run across this sooner, I might not have wrote my own very similar wiki. (https://github.com/cu/silicon)

Otter is much nicer, though.

do you know a wiki where one can add metadata to the pages?

I used https://foswiki.org and it was great for combining structured and non structured information

I use Dokuwiki with the Struct plugin.

I've been playing around with dokuwiki recently but this looks promising.

The irony I'm having is that I store some single file html documents alongside my notes and none of these engines (or obsidian) will render them!

We use Confluence at work. It has the option to render HTML embedded in the page. I haven’t tried to render a whole file attached to a page, but there might be a way to do that.

I’ve used it a bit to add my own forms into pages to create little tools for people in docs.

In the past we used Jive, and I had a rather involved HTML paged embedded there. I had to be careful with my CSS, as using any generic attribute level CSS would break the platform. I hope Confluence has protections against that, but haven’t tested it, as I got in the habit of avoiding that issue all together.

Every new wiki / knowledge management system I always compare against Confluence. I get the advantage of keeping your content in plaintext for portability but when I look back on how many times I've actually ported wiki content it's... maybe once? Most systems these days are handily capable of this, in any case.

Anyway, Confluence for all its flaw has so much power, is so much more pleasant to use, your business folks won't balk at it. As often as not, we have people from all parts of the company in there, reading and writing both, and it needs to be usable to people of all technical levels. Markdown wikis and their editors don't often meet this criterion, or they're missing on some key features (tables!!).

To me, Confluence's only real down side is that it's an Atlassian product. I wish I could find something to scratch the itch without feeling the need to buy into that whole ecosystem.

> I get the advantage of keeping your content in plaintext for portability

Portability is secondary for me. For me, the primary reason for keeping content in plain text is disaster recovery.

When my systems are down, when my applications aren’t working, if my documentation is also inaccessible, this makes things a lot harder.

If my documentation is primarily in plain text / markdown, it’s really easy to be able to read those docs again, even when everything else has fallen over.

I’ve made some of my tools with this in mind, because they are for a team that has to keep functioning during a disaster recovery situation.

I stubbornly kept the main page as HTML. All libraries are download and sourced locally, instead of using a CDN. I use as little server side as possible, and just use basic PHP when I must. The idea being that in a worst case scenario the users can simply open the index.html on their desktop had have 95% of the functionality. If they run something like xampp, they can get 100%. This app is basically their map to the rest of the infrastructure, with some helper tools. They’d be lost if it went down when they needed it most. That said, it’s never come to this in 15 years and there have been several big DR events in that time. I still like having it as an option in my back pocket.

I recently handed it off to someone else to manage. I should probably share this part of my philosophy as it seems like they are trending toward adding complexity and dependencies, because they’re hip and cool.

Or you could just use fossil...

Is there something similar but instead of being minimalistic mediwiki alternative, it's a minimalistic wikibase alternative?

Is there anything git-based like this having semantic web stuff support similar to Semantic MediaWiki?

I love this, but so many of these are missing or have a half baked Annotations feature. I've been looking for something that that for years and none of them work well for this purpose. Mediawiki, Dokuwiki, Xwiki, etc.

Can you explain what you need in annotations that doesn’t exist in these wikis?

Isn't "poweredy by python" kind of defeating the purpose of using markdown and git? Well I don't mean python as a language, but python as running as a web service/app.

Usually when your website is hosted on git as markdown files, that is because you'd rather have the website generation separated from serving the actual content to the public, i.e. having a secure and dead simple static website.

If you start having to run a service/container, that generate the content on the fly and plan to edit the website using the browser, I don't really see the advantage of hosting the content on git vs a database. That database can be as simple and easy to host/backup/manage as a simple sqlite3 file and would still be more efficient than a git repo as a storage backend.

No, this isn't always true.

I have hated every WYSIWYG intranet my employer has used. I just want to write Markdown.

Luckily, we also had access to a file server with ~/public_html and httpd with PHP.

So I just threw PHP Markdown Extra and a htaccess file up, now I can write in Markdown and it magically works. If that was done with Python I wouldn't care either.

(that old webserver has since been retired and the new one doesn't have PHP, so now I render locally with Pandoc and rsync my HTML files directly, sigh)

I agree, there are two things I miss with markdown: import/export of text + media, multi user editing. This is always an extra step when you do not have and editing builtin in the Wiki that handles that. The "paste" image into document feature is one of the most useful features of a wiki if you want to write a fast bare bones tutorial.

The purpose of using markdown is to make editing simple. The purpose of using git is to use a well-known and rock-solid history-preserving file store. Both of those purposes are orthogonal to method of delivery and tech stack used. So no.

In general, i agree that static site generation is preferable to dynamic rendering where possible, because it makes for a much simpler and more secure deployment. But a wiki has to support editing of pages in the browser, and authentication of users before they can edit, and you need a backend for that. Also, if you want to support browsing of page history, a static site generator would need to render every version of the page upfront, which feels like a bad idea to me.

> That database can be as simple and easy to host/backup/manage as a simple sqlite3 file and would still be more efficient than a git repo as a storage backend.

With git you will have the latest version of the file in the filesystem, that must be more efficient than retrieving it from sqlite3, mustn't it?

I am not sure that retrieving it is the correct word. In term of efficiency you have to take into account the overhead of multiple files, some in cache, some not vs 1 single probably already cached file

Also https://www.sqlite.org/fasterthanfs.html

Looks good. I like the small memory footprint a lot!

It would be nice to have a WYSIWYG text editor for the markdown or to have a live preview next to the markdown.

I've been using it for while, recommended.

quite sure that is my limit but what is the difference between this and other "md compiler" projects (or ssr) like <https://github.com/rust-lang/mdBook>? Anyway this seems to work very well, so congrats!

I like it. My site (taoofmac.com) is also git/python-backed, although not live editable.

I ran https://wave.webaim.org/ against the homepage, saw 11 errors right off the bat, and decided not to look at further.

Particularly for this kind of project, though as an accessibility person I'd argue every project, accessibility is table stakes.

You could, perhaps, consider filing an issue or fixing some low-hanging fruit.

I see no backlinks, no "what links to here" section.

The "Edit an Example!" link goes to Forbidden.

If you login, you can edit

Here's why I didn't access the link: I'm never interested in any product that the main feature is the technology it uses.

Which problem does it solve? Not how it is made.

Why, how it's made is also its interface, and its operational requirements. Both are important.

- Markdown: widely used, readable, well-supported by other tools.

- Git: ubiquitous, well-supported, likely already present and set up.

- Python: ubiquitous, well-supported, easy to read and hack on; sometimes a pain to deploy.

If the above is not relevant for you, well, you'd be better served with opaque one-click-installable apps from App Store. Not bad, just different.

The title here was an editorial choice by the person who submitted this link to Hacker News.

I have a hard time using the word "minimalisitc" to describe any site that requires javascript to function.

Reply on news.ycombinator.com