Hacker News new | past | comments | ask | show | jobs | submit login
Minisleep – A Tiny Wiki Engine (halestrom.net)
139 points by merlinscholz 68 days ago | hide | past | favorite | 55 comments

I'm Hales, the author of Minisleep. I'm open to any and all questions, critique and tangential stories.

I made Minisleep to solve the problems I had with other wiki engines and it's been doing this well. It runs my personal blog website, a few websites of clients/employers and a home wiki that gets touched once every two years when I organise a LAN party. I'm not sure if anyone else on the internet uses it outside of that (Minisleep doesn't contain any install tracking or unique IDs).

EDIT: Although I did discover a russian linux forum mentioning it last year. The world has changed quite a bit. https://www.linux.org.ru/forum/general/16473170/page1?lastmo...

Have you thought of somehow mitigating brute force auth attacks?


Normally I hate passing the buck like this, but this is something you need to configure in your HTTP server (not Minisleep).

Minisleep does not handle auth itself, instead HTTP_AUTHENTICATION is handled by your HTTP webserver. Minisleep's scripts do not even get run until authentication succeeds, so they have no way of noticing brute force attacks.

I did have code once where minisleep itself handled auth checks (instead of your HTTP server), but I realised this was probably making things worse. You would have to trust my auth checking code AND my rate limiting code AND it would be easier to DDOS. My rate limiting was also a bit naive, blacklisting by IP, which probably isn't enough when facing modern IPv4 botnets or IPv6 in general.

My personal website (https://halestrom.net/) has a commenting system which does do some simplistic rate-limiting in CGI scripts. It's a bit easier there, because one of the rate limits is site-wide, and there is no auth to check, so I'm a lot more comfortable with it.

Thankyou for bringing this up, I need to add some docs about server ratelimiting configs (and add them to the pre-made example server configs I ship with Minisleep). I'm so used to using ridiculously complicated passwords that I have forgotten about brute forcing practicality.

I think about rate-limiting from an unprivileged user perspective and saw it first at https://github.com/sebsauvage/Shaarli/blob/master/index.php#.... So e.g. fail2ban is not an option. And the application has to deal with it.

I care more about load/DOS than actual crack success. What means the firewall is the sensible place. Not the application.

Or just take the risk, make backup/restore simple and do intrusion detection by monitoring a dedicated endpoint with e.g. https://updown.io/44q5 and let things happen for the sake of simplicity.

Hm. (I'm doing a federated, single-user microblog engine targeting laypersons. A proof of concept is at https://codeberg.org/mro/ShaarliGo)

You can mitigate it by having a very long password :)

We need graphs of "minimum password length" versus "number of CPUs in your shared hosting" :D

lol, indeed. However I would prefer something with less load impact than bcrypt hashing. Or is that yak shaving?

what's your take on tags?

I love the idea of tags/categories on sites. They're an alternative navigation strategy that I particularly like using when reading people's blogs.

I have not implemented tags in Minisleep's releases because, whilst doable, they are a bit messy and complex for this codebase. I want people to be able to fully understand what's going on in Minisleep so they can feel confident extending build_page.sh and adding custom script-pages themselves, not be worried they might be breaking some feature somewhere else that they don't know about yet.

Currently Minisleep's philosophy is "editing one page only modifies that one page". There are no central indexes. You are free to re-arrange, delete and create folders and files yourself, the worst you will have to do is re-run build_page.sh afterwards to update hyperlinks on a page.

Adding tags requires you to generate and update centralised pages regularly (eg every time a page has its tags changed or is deleted). If anyone modifies pages in a way that does not trigger these updates: things break.

Another (but more minor) issue: Minisleep's page relationships are hierarchical (folders) not relational (ala SQL). Tags are a bit more relational, ie different pages are arbitrarily related. For the pages themselves this is not a problem (tags are just a list of links somewhere on the page, no need to reference external materials when generating them) but it means the central tag pages (listing other pages with x tag) need to be made by trawling through _every_ page on the site manually with no optimisation.

In reality this is mostly fine, it's not really that performance demanding unless you have a wiki with thousands of pages or more (at which point you probably are not using Minisleep). I do it this way on my personal website https://halestrom.net/ for generating the front page index of articles and comments, with some hacked-up half indexes. It's a mess but it works, and that's exactly the sort of thing I want users to hack up and add to their Minisleep sites themselves, rather than accept as a mess from me.

thanks, indexes indeed may provide most what's expected from tags. At a way lower cost. Wicked.

(In my microblog engine I go lengths to automatically maintain redundant entries in directories e.g. https://l.mro.name/o/t/CGI/. But a microblog is a different story)

> thanks, indexes indeed may provide most what's expected from tags. At a way lower cost. Wicked.

Sorry, I'm a bit lost. Aren't they parts of the same thing? When you put tags on pages you also need an index of all the pages with that tag?

> parts of the same thing

yes, from opposite angles.

Adding a page to an index may be more obvious than adding a keyword to a page. Both UX-wise and technical.

I like the spirit of it. For me, what would most give a wiki lightweight, efficient user experience is in-place editing, like a word processor. It's so much more efficient - imagine the reverse, if Word required you to reload for every edit! In detail:

* In wikis I've used, editing requires 6 steps and 2 page reloads: 1) Find existing content/location on page (on pages that aren't tiny), decide what/how to edit. 2) Switch to edit mode (page reload, and lose my place). 3) Find existing content again. 4) Edit it. 5) Save (page reload, and lose my place). 6) Find new content and verify it.

* In-place editing, as imagined, would be 2.5 steps, no reloads (again, like a word processor): 1) Find existing content on page, decide what/how to edit. 2) Edit. 2a) Verify it.

The cumbersome nature of the current process consumes a lot of time (I'm a heavy user) and deters a lot of editing. I wouldn't even mind an 'in-place' mode change, where I didn't lose my place and didn't have to wait for a reload.

How difficult would that be? Does any wiki do it? I would be willing to help pay for its development, it would save so much time and also so much cognitive overhead.

Tiddlywiki seems (from a technical perspective) a little bit closer to what you're imagining:


Sadly it doesn't let you edit WYSIWYG, ie when you click "Edit" it still transforms the section back into monospaced markup script in a textarea.

Theoretically it should be possible to change that, but I have not looked at the codebase.

If you were to do this from the ground up you would probably:

* Enable .contentEditable on the whole page (or at least sections like <main>)

* Add a floating toolbar for formatting controls (and a save button)

* Do the submit in javascript, so the page doesn't have to fully reload.

* Possibly add a toggle edit button? Or would people be comfy being able to accidentally edit pages whilst reading (as long as they realise they have to hit "save" to make a change). This might ruin some people's navigation key shortcuts in their browser (eg users of Vimium).

For personal or small-team use I could see this being good. For larger teams it would be a nightmare, as accidental edits would be common. The formal 3/4 step editing process has its problems, but it's a useful barrier against the tides.

Alternatively you could stick to using MS Office/Libreoffice, set the view mode to "web" and hyperlink to subheadings as your navigation (instead of "pages"). If we wash our minds of the historical uses of word processors versus web browsers: this could be a very successful implementation for 1 user or a few users (on a network share).

Thanks for this!

> Sadly it doesn't let you edit WYSIWYG, ie when you click "Edit" it still transforms the section back into monospaced markup script in a textarea.

I actually prefer that; I didn't mention it because it seems like additional complexity that few besides me would desire. I'd rather edit using markup; it's much more precise. Heck, I could use an extention to add a Vim UI to the textarea and I'd be in heaven.

> Possibly add a toggle edit button?

I think that would be important in most circumstances, to facilitate a reading UI (including navigation, as you mention) and to prevent accidents and make editing more of a thoughtful choice.

> The formal 3/4 step editing process has its problems, but it's a useful barrier against the tides.

We could still have required preview steps, without waiting for reloads and losing our place on the page.

> you could stick to using MS Office/Libreoffice, set the view mode to "web" and hyperlink to subheadings as your navigation (instead of "pages").

I thought about that. Several problems, mostly related to complexity of word processing: Over many years and edits, word processing documents become a mess; text-based wikis are invulnerable. Also, it's harder to create simple structured documents, with proper formatting, in word processors (and things become a mess again), where wikis again are very simple - just use the header/subheader syntax. And word processors are paper page-oriented regardless of mode, which is more complexity and also an absurdity in a wiki.

I recommend you try Federated Wiki [0]. To test out its editing process:

1. Go to: http://fed.wiki.org/view/how-to-wiki

2. Once you're there, click the "wiki" word down in the grey footer. A checkmark will appear next to the word "wiki."

3. Double-click a paragraph and edit. Ctrl-s saves. The page you edited will gain a yellow halo. The yellow indicates that your changes are only being saved in your browser's local storage for now. (If you have your own site and are logged in, changes will be saved on the server.)

I run my own Federated Wiki (fedwiki) server. You can also just run it locally (which I do sometimes). It requires nodejs. I was a bit fussy with my server setup and have lighttpd as reverse proxy (I think that's the correct terminology) and 'supervisor' as nodejs babysitter, but most (all?) of that is not strictly necessary; fedwiki can just run on its own.

[0] https://github.com/fedwiki/wiki

EDIT: Clarity.

That's fantastic, and it's UI seems very efficient. Thank you!

In-place editing is only good for private documents. For publicly viewable documents I absolutly want the edit-preview-edit-preview...publish steps.

Trying to optimize those away is optimizing the wrong thing. It's like parking your car in your bed room to make it more convenient to get from the bed to the car.

> For publicly viewable documents I absolutly want the edit-preview-edit-preview...publish steps.

If you want to preview before publishing, you could still do it with edit-in-place.

> In-place editing is only good for private documents.

Many wikis (including some described in the OP) are private or only used by a few people. Wikipedia is an exception, not the rule.

That's like saying many papers are used for private documents.

I think you are overlooking the use of personal knowledge bases, including wikis.

What are we even talking about any more? The post was about some wiki sofware. Of course some people may use it in a private context. So what?

Trilium Notes might be what you are looking for. Very very pleasant


Looks nice. Fossil (fossil-scm.org) is a lot more code, but it's written in C and is quite fast and does a lot (bug tracking, version control, etc) besides having a built in wiki. Its running image is about 40MB. Its default web page layout isn't that great for a pure wiki, but that should be hackable if not configurable.

Wait, I got mixed up, and it's past the 2 hour editing window. 40MB is the ram footprint of Gitea, which is written in Go. Fossil is a lot smaller, like 2MB IIRC. It has been a while since I played with it. It is basically a small C framework wrapped around a bunch of SQL scripts that run in an embedded copy of sqlite.

Ooh I like the idea of using SQlite. That would make backing up the site and moving it to other hosts much easier.

I'm going to have a look at Fossil if I need something more than Minisleep :)

I use zim wiki for desktop wiki / knowledge base for my personal stuff. The biggest hurdle I have had with any wiki or knowledge base stuff is to actively using it and improving it. I find myself adding stuff in bursts and then not using it for weeks.


I really liked Zim many years ago and used it quite a bit for personal note taking, but its lack of tables really annoyed me. I love tables with a passion.

(On that note: when you add table support to a markup language PLEASE support newlines and paragraphs inside table cells. Don't assume that all tables are spreadsheets with only a small amount of text per cell. Some of us live in tables like high-rise apartments, eg bug tracking, school note taking & image stacking in cells.)

Zim does support tables and has support for newlines in cells, but they are basic, no markup, limited manipulation.

If it's non-numeric data and needs to be in tables the best program I've found is treesheets. Absolutely brilliant program.

Ahah, I found the tables! You have to go into Zim's settings and enable them as an addon in there. Ty, I thought there was no support whatsoever (other than putting pictures of tables in https://github.com/jaap-karssenberg/zim-wiki/wiki/Create-a-t... ).

Indeed it still seems a bit limited. Nothing like Firefox's in-built table editor used to be (this is the one in Thunderbird, which is quite nice). I wish they hadn't removed that feature :|

Treesheets is a beautiful program, but I'm too much of a pen-and-paper + plaintext notes person to appreciate it properly.

Yeah they can quickly turn into the junk drawer in your kitchen. Things go in there to never be found again.

I just spent twenty minutes banging away - and this is the wiki I've been waiting for my entire life. It does exactly what I would want from a WIKI server, and has pretty much zero dependencies other than /bin/sh.

The built in WYSIWG editor is great. Handles Images flawlessly. Add Folders. Edit Pages.

Time from downloading the tarball to having everything up and running was < 60 seconds in WSL.

What version of WSL and what webserver, if I may ask?

   Microsoft Windows [Version 10.0.19043.1645]
   λ wsl --status
   Default Distribution: Ubuntu
   Default Version: 2

   Windows Subsystem for Linux was last updated on 4/3/2022
   WSL automatic updates are on.
   Ubuntu 20.04.4 LTS \n \l
   lighttpd/focal-updates,now 1.4.55-1ubuntu1.20.04.1 amd64 [installed]

Kernel version:

Ty, appreciate that.

From what I understand WSL2 uses a virtualised Linux kernel, so it makes sense everything is similar enough to work there. I've heard lots of people like to use WSL1 instead, but I'm not sure of its future.

The author wrote critiques of mediawiki, tiddly, but what about Doku? It's mentioned in the article but I was wondering what's bad about doku since the setup process isn't too bad imo.

(I'm the author of Minisleep)

It's been many years, so my memory is a bit rusty. I think I recall it being fiddly to upload images for a page and possibly the themes were complex to modify (?) (I didn't like the default and wanted to make something simpler).

I can't be certain, I have not tried Doku in years. It looks like a lot of places use it now and its seeing success.

Photos are now very simple to upload to Dokuwiki.

There are a decent bit of themes too, I havent tried creating my own though.

I don't understand why Dokuwiki isn't more popular. It is super easy to use, there are a good bit of themes and plugins that can be installed through the GUI, it loads pictures fine (and has a little picture tracker interface where you can browse uploaded photos), you can use the farmer plugin to multiple seperate wikis on the same website and it doesn't require a database (all the pages just sit in a folder you can copy/backup anyway you like) so it is stupid simple to backup.

I think it is kind of a shame really, Dokuwiki is a beautiful bit of software in my opinion.

Yep, compared to MediaWiki(last time I set it up was like ~7 years ago) it was such a hassle to setup. I think my main complaint about Doku is that it's built on PHP. I haven't tried to hardcore customize things other than installing plugins and templates though so I can't say how easy it is to extend.

> I think my main complaint about Doku is that it's built on PHP.

How is that a complaint? PHP is thoroughly battle tested and works on any cheap shared hosting. It's the perfect choice.

personally I try to avoid all dependencies (except a mere webserver, naturally) when it comes to reading.

I love the dokuwiki no-db filesystem storage approach, however.

Computer software seems to go through phases of complexity. It starts out simple, then people add necessary features until eventually someone thinks it is too complex and builds a simple version, which then starts along the same path to complexity. This happens to programming languages and operating systems as well as apps. Part of the desire for simplicity seems to be younger programmers who don't like dealing with all that complexity and all the "poor decisions" made by past programmers (the oldsters). It was once thought that computer programming would become mature and we'd be re-using lots of code. Instead copy-paste is now considered code re-use, API's get deprecated, and there is endless churn and reinvention, a lot of which eventually also gets tossed. Maybe every generation of programmers likes to do things differently and choose their own variable names, etc.? I think we'll know that programming has become mature when there is no longer a need to create new versions of compilers. Or maybe the reinvention is necessary as a way to learn how things actually work? In practice it feels like being stuck in a time loop, I've seen it happen so many times.

You seem to be looking at software as a dead artefact like a greek temple that was built hundreds of years ago and that still stands. But it is also an element of culture.

In my mind, software only half-way exists on the disk. That's the artefact-part of it.

It also half-way exists in creators' and users' heads. That's the culture-part of it.

If you take any piece of culture, like music or dance or cooking, then you'll quickly start to see the parallels. Both the craft of making the music, doing the dancing/cooking etc and the discovery/appreciation of music, dancing, cooking etc has to be passed along from generation to generation and spread through social networks to keep it alive. The fact that bits don't rot is just not enough. It takes active engagement and cycles of invention and reinvention to keep it alive.

I think this is quite a liberating thought. Conversely an "oldster" saying something like "I did this first, so no one is ever allowed to do it again" feels highly oppressive to me, and feels like that oldster taking away from the world more than they're giving.

The process of invention and reinvention is highly productive, because of the selectivity of how good ideas (like wikis) keep getting reinvented while bad ideas (like XML) don't. Software, like science, advances one funeral at a time [1]. Once Oracle had built XML-capabilities into their databases and people started using them, could you imagine Oracle going "oh, on second thought, let's remove that and break backwards compatibility"? I can't. Nowadays you have tons of people trying to reinvent the database. Can you imagine any one of them going "Hey, let's pour a lot of man-hours into building XML support and convincing all our users to make heavy use of it"? I can't. That's a good thing.

[1] https://en.wikipedia.org/wiki/Planck's_principle

Do you have (or can you add) configuration instructions for OpenBSD and its built-in httpd?

Sorry I've never used OpenBSD.

It looks like OpenBSD's httpd does not support CGI, instead it only does FastCGI:


You then have to use a wrapper to convert FastCGI into CGI:


I wouldn't bother with all of this. Use a http server that has your back from the start, don't layer more protocols and add daemons where you don't have to


I wonder: if CGI isn't enough for a project then wouldn't it be better to talk HTTP natively yourself and go through a HTTP<->HTTPS proxy rather than talking FCGI yourself and going through a FCGI<->HTTPS proxy? I'm not sure, I have not tested both routes, CGI is more than enough for my uses.

made an account to say that I love this. it is exactly what I wanted for keeping track of thoughts and "where did I leave ..." types of things. more than a text file but less than setting up something far more complicated. thanks.

I’m looking for a wiki written in Go that has back links (referenced by) support.

Does anyone have recommendation for a wiki with a programmatic api?

I feel like this could be containerized fairly easily?

for what benefit?

If you are hosting a bunch of services in Docker already it's easier to just add another image than doing something custom that you have to update in another way then the rest.

> doing something custom

I hear that all the time.

What services do you think of when thinking about static sites and a dash script?

Sounds to me like adding complexity just because everybody does it. Cargo cult.

It’s not about adding complexity, it’s fitting it alongside all the other services you might run.

If every service, complex or as simple as a static site can be updated, stopped or having a backup done in the same way it makes things easier. Even if this very service wouldn’t necessarily need the complexity.

a CGI in sh. Nice move contrary the mainstream.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact