well okay, that's not fair: the real title should be like “making dokuwiki pretend it's a blog despite that being an unreasonable request.”

as noted in my previous post (making a website is hard) there are no longer any tolerable software packages for creating “a site that works like blogger did in 2006.” your only choices at this point are to let node.js consume you (and i don't even know if that'll really get you what you want) or to beat some unrelated tool into a bloglike shape. this is what i've done to create this site - you are currently looking at a Dokuwiki instance, which i hope will be a sustainable solution, though really who knows anymore.

i ended my previous post by calling dokuwiki “this goddamn thing,” but i really mean no disrespect, it's honestly quite cool and capable. most wiki packages are either way too simplistic, or they're Fucking Mediawiki. MW really does not want to be anything other than wikipedia.org so if you don't want a site that looks exactly like wikipedia.org, uh… good luck with that.

doku is a nice in-between option in terms of size and complexity. it doesn't require a database, which is good news for a whole bunch of reasons:

• fewer external dependencies to set up

• one less thing to break

• moving doku to a new server consists of copying the files to the new server

• if you decide to bail on doku, parsing the files to convert them is trivial: this article is stored in “data/pages/blog/dokuhacking_1.txt” in plain text.

it's also trivial to set up. in the classic tradition of PHP scripts, there is no installation process; you extract a zip and now you have dokuwiki. there IS an install.php but it just sets your password and squares up some permissions, then you delete it. it's technically optional.

dokuwiki is also very fast, highly extensible, reeeeeelatively easy to hack on, and extremely unpretentious: this is not a Product, it does not care if it's appealing to businesses that want to look shiny and hypercompetent so they can scam you. it is classic nerd software, like linux in 2002. it's honest, and humble.

there's a lot to like, the problem is just… it's the Trac Ticketing System of CMS software.

and you know, that's really a great example, because if i was setting up a ticketing system i would probably use Trac! it too is pretty simple to configure, highly capable, and values function over form. the problem is just that it… values function over form.

both of these things feel incredibly Web 1.5, which makes sense since they were both launched in 2004. still, it means their default templates are outright embarrassing, and while they're perfectly serviceable in functional terms, if you actually want strangers to look at or use them, you have to do something about the UI. namely, get rid of… a lot of it.

of course, that's where being stuck in 2004 has its advantages: the code and templates are sufficiently simple that i can hack on them, and more importantly, in eight months when i upgrade and need to figure out what hacks i'd made so i can reapply them, it won't be that hard to reverse engineer my own work. the codebase is not terribly convoluted. i mean, it has a plugin infrastructure, so there's some abstraction going on; you have to learn a little bit about events and hooks and template parsing, but this is all just PHP, so it can only get so complex. for the most part, i figured out how things worked in a few hours, with PHP knowledge from 20 years ago.

the problem however is that some of the code is… not of the highest quality to begin with, nor particularly well maintained. i mean, for all i know doku itself is full of security holes, but i'm not that worried because it's isolated into its own server and i can make backups; w/e. it's updated at a moderate pace, and while i think it's maintained by a very small group of people (possibly just one or two?) the core codebase is pretty mature and if it were that insecure i think nobody would be using it.

the bigger problem is the plugins. instead of adding large amounts of behavior to dokuwiki itself, they leave it to the community to add it with plugins, and naturally, the overwhelming majority of these are abandoned. some have not been updated since 2019; some not since 2009; but even some that were updated within the last few months have been broken by recent updates, or just had major bugs to begin with, because this program just simply does not have that many users or contributors. if a plugin gets abandoned by its original author, it usually never gets picked up again. so, while it's easy to google “dokuwiki [feature]” and see, “oh, there's a plugin for that,” you might install it and find out that it breaks your whole site, or has serious bugs, or is in, like, alpha status and not getting any updates.

as with many FOSS projects, there's just a lot of people who show up, make one really cool commit, then go off to University and are never heard from again. it's rough, albeit expected.

the result though is that i've had to manually patch three or four plugins to make them work at all, to fix major bugs, or to add simple functionality they just never got around to including. but, i mean, at least that was possible. in a larger, more modern package, there is no way i would ever be able to navigate the Brave New World of rust or ruby or node.js to understand what the fuck it's doing, let alone make any changes, and then if i did, they'd simply get reverted a week later by a mandatory update. ugh. so this is the price i pay.

regarding the plugins themselves: as noted, dokuwiki does not want to be a blog, it wants to be a wiki. to make it pretend to be a blog you need a lot of third party functionality. i'm running all of these:

• blog
• pagelist
• include
• prosemirror
• imgpaste
• iframe
• smtp
• discussion
• feedmod
• cmsmode
• searchtext
• text

these all modulate dokuwiki's behavior, some in very subtle ways, but they're all mandatory. the blog plugin, for instance, simply allows you to put a special token on any page you like, which will be replaced by a list of every page in a given “namespace,” which is basically (and literally) just a directory in the wiki structure. there is nothing special about the index page; if i write “{{blog>1}}” below this, the latest blog post appears:

<< Newer entries | Older entries >>

the blog plugin itself is incredibly simple: it's little more than a macro leveraging the 'pagelist' plugin, which does exactly what it sounds like, it lets you generate lists of wiki pages based on criteria, and then the 'include' plugin lets you include the contents of one wiki page inside another.

prosemirror is a visual editor; more on this shortly. imgpaste is a little extension that lets you paste images into the editor instead of having to save them as files and upload them, thank christ, i hate that shit. iframe literally just makes iframes possible, i can't recall exactly why it was necessary but it's very simple and does what it says on the tin. discussion adds comments, smtp lets you subscribe to comment update emails. feedmod lets me frobulate the RSS feed so that pages get proper titles instead of miserable_ugly_underscores (i also hacked it a little to clean up some of the other fields.) cmsmode lets me disable a bunch of wiki-specific features, and text/searchtext make the built in search tool strip out all the formatting so searches are a lot cleaner.

putting all of these together lets you make something much like a blog. you can see the rough edges, but it's close enough. this is very much a unix mentality of “tiny tools chained together,” but of course, it also includes the second part, the part nobody ever says. the full description is “tiny tools chained together, offering only about 75% of the functionality and 15% of the convenience of a single purpose-built tool.”

for instance: the include plugin has no idea it's being used to create a blog index, and dokuwiki has no internal concept of page titles, or of a page having a “summary,” so the blog plugin performs a lot of hacks. to make each page appear in the index with a nice looking title and a “read more” link after the teaser, it has to:

• slice off the first heading it finds in the text and treat that as a title
• slice off the SECOND heading it finds in the text and treat that as a “read more” break
• … Although it doesn't hide the aforementioned heading when you actually look at the post, so I had to install yet another plug in that just lets me hide headings by adding a little bit of gibberish to the header tag.

include has been extended with these capabilities probably specifically to enable the blog plugin to work correctly. i'm sure the maintainers planned this, but that doesn't change the fact that these are separate chunks of code that don't entirely know what each other are doing, so you do have to go in and set like six checkboxes in the enormous dokuwiki config page to make it work this way.

on the other hand, it's neat that you don't have to! if you WANT every single post to appear in full, you can just… do that! and if the functionality you need doesn't exist, it's not that hard to hack in.

example: the blog plugin adds the concept of “drafts.” there are actually many plugins to add this to dokuwiki but i didn't want something too complicated; the blog plugin simply allows you to add ~~DRAFT~~ to a post, anywhere you like, and that will hide it from any blog index. there are a few problems with this.

problem 1: drafts still show up in search results

solution: i downloaded a plugin that lets you add a “hidden” tag to posts to hide them from searches. it was like 30 lines of code which i copied into the blog plugin, made a couple adjustments, and now drafts don't show up in searches. i did this live in production and it wasn't a problem because i didn't have to restart an App every time i made a change, let it precompile, and then have it crash and kill the entire process, shutting down my whole site. when my code was broken, it only affected the search page, and only for 20 seconds until i reverted it.

problem 2: drafts still show up to anyone with editing privileges. this confused the HELL out of me at first - i marked a post as a draft, then saved it, and it showed right up on the index. it took me an hour to realize i needed to log out, then it disappeared.

solution: i added a hook to the RENDERER_CONTENT_POSTPROCESS event which detects if a page is a draft, then appends a big “DRAFT” banner to the top. this worked when viewing posts directly; to get it to appear in the post index, i had to modify the “syntax” script, which is what replaces the blog tag with the page list.

$renderer->doc .= "<div class=\"blog-post\">";
// Write draft banner if appropriate
if(p_get_metadata($entry['id'], 'type') == 'draft') $renderer->doc .= "<div class=\"draft-banner\">DRAFT</div>";
$renderer->nest($inst);
$renderer->doc .= "</div>";
$this->included_pages[$entry['id']] = false;

like that. and because this isn't written in some gargantuan Framework, i didn't have to figure out how to instantiate an Enterprise Div Bean subclassing an Element Bean and inject it to the Layout Queue by submitting an Async Rendering Intent. doku does have a very obtuse rendering system tbh, but you can ignore it entirely and just do some printfs or string concatting. it works fine. you do not have to do everything “correctly.” thank christ

okay, here's another example that happened while writing this post:

when you embed an image in a post, obviously you want it to get thumbnailed, and for the thumbnail to link to the full picture. this is how the web works, since time immemorial. doku supports this, and it does it using a time-honored tradition: rather than linking to the image directly, it's routed through a PHP script, “fetch.php”, which confers a lot of benefits. you aren't exposing your media directory to users, security policies and permissions can be applied, and of course, you don't have to keep a pre-converted thumbnail version of every single file.

the masterchief here is being displayed at like 160×300, because fetch.php is being called with parameters like width=160 and it's scaling appropriately. this puts a slight CPU load on the server, but CPU is cheap; it saves bandwidth, the really important part, and it allows me to change the thumbnail size at any time without needing to delete and regenerate files. hooray

but when you click on that image, by default, something terrible happens: instead of just showing you the raw file, it generates a weird little that puts the image in a fixed-size box, then displays a bunch of EXIF metadata and navigation links at the bottom. awful! detestable! who would want this! eugh!

the only solution proposed by the doku people is to change the embed link from

{{.:pasted:90.png?120}}

to

{{.:pasted:90.png?120&direct}}

this will change the link target to do what you want. but there is no way to make this the default behavior! awawghghh! no! i am not editing every single goddamn image i link like this!

fortunately, i made a discovery: the “detail” page is called “detail.php”, while the normal “get me the whole image” link is “fetch.php”. so i simply deleted detail.php and symlinked the name to fetch.php; this fixed it, and i didn't even have to edit any code, because doku is built the way it should be: a loose collection of files that anyone can understand.

this is, again, why i went with dokuwiki - because it's one of the last vestiges of classic nerd software on the internet. it's like linux in 2003, before it started trying to Help you, before it started trying to be a mishmash of half-baked, half-remembered ideas from Windows and MacOS that don't make end users all that much more comfortable, while getting in the way of the people who the OS was meant to be for in the first place. just let me ifconfig an IP onto eth0 you jackoffs, stop Managing my Network.

i hate modern linux. it has been going in the wrong direction for over 20 years, trying desperately to suck up to consumers who will never care about it, like the democrats “reaching across the aisle” to people who simply bite their fingers off for their trouble, while doing immense harm to their own constituents in the process. and that's really a microcosm of all free software, it's why every other open source CMS package reeks of business-brain.

enterprise brainworms have taken over so fully that you just can't find something at the triple point of “good idea”, “well maintained” and “actually useful for normal human beings,” which is, again, how i wound up using a piece of software from 2004, before the collapse began in earnest. it's like finding steel that isn't radioactive due to fallout from nuclear tests: you simply have to go dig up the old stuff, even if that means melting down old car chassis.

i still don't have a great WYSIWYG editor. nerds really hate these and i don't know why. yes, i know you want to do everything in a greentext ssh session and pretend you're hacking the matrix; that's great, go ahead, have fun, but surely someone other than me recognizes that editing rich text in plaintext is a gigantic waste of time and effort that adds a ton of context switches and repetitive try-confirm loops to the basic act of writing. this is how we did it in wordperfect, but then we stopped needing to do it in 1985 when the first word processors for mac came out, and even earlier if you worked at a place with a xerox system. i can't be the only one who sees how regressive markdown is, but it really feels that way.

and i mean, this IS a solved problem, even in the FOSS space. there are plenty of excellent free WYSIWYG editors, i've used several, but they're never core components of anything. they're always just standalone javascript objects being offered up for integration, and nobody wants to do the integration.

the primary maintainer(s) of dokuwiki do not want a graphical editor, they think editing in raw wikitext (like markdown but different) is the way to go, and therefore they don't think a GUI editor should be built into the project. they don't mind it being available as a plugin - but of course, you can't do that. the editor is so core a feature that for it to exist at all, the project has to select and commit to a single tool, then all core and plugin code has to be tested rigorously against it. otherwise it will break as soon as anyone changes… anything, basically.

this is, naturally, what has been going on forever. CKGedit has been the standard plugin for a very long time, integrating CKeditor, and honestly it works pretty well. i'm using it right now! but it IS dated, and people have proposed replacing it several times. finally someone did, adding the considerably more modern Prosemirror. that looks great, but i tried it, and it breaks completely when i embed certain plugin features, and none of the keyboard shortcuts work. i can't hit ctrl+i to italicize some text, so it's basically useless.

there's an issue open for this, and it has been open for a long time, but it's not getting fixed because this is simply nobody's priority. plus, it's whack-a-mole: it'll get fixed eventually, and then someone will change some incredibly minor thing in dokuwiki and it'll break again, and once again it'll take another year to get fixed. nerds always turn up their noses at any suggestion of graphical editing, so this plugin is always going to get fourth-rate support, rendering it essentially useless.

indeed, CKGedit doesn't seem to have been updated in two years - but as far as i can tell, it still works. i mean, it's not perfect; while I CAN paste images into this,

and it simply uploads and embeds them instantly, meeting my bare minimum requirements, i still can't drag images into the editor from an explorer window. i'm not sure why. this is supposed to work, i have a plugin for it, but… no dice. some minor thing must have changed to break it, and hopefully eventually someone will fix it - but in the interim, i can still use the manual upload button in the editor.

this adds a step that shouldn't need to exist. i mean, in 2004, absolutely nobody expected drag and drop to work, so by the standards of the time this is as good as it ever got. conversely, we should have expected it to work. conversely, by installing dokuwiki i had already decided to abandon modern functionality in favor of something that works, per the standards of some era, instead of failing to meet the most reasonable expectations of anyone in any era, so… i guess I'll just take what i can get. after all, this must be good enough, or you wouldn't be reading this post at all, would you?