README.md

Rat-Tools

Created: 2023-11-15, Updated: 2024-04-25

This repo contains and describes some of the specialized tools I use to maintain my website, ratfactor.com.

They’re uniquely awful, which is a classic case of “the cobbler’s children are the worst shod” (wiktionary.org).

Someday I hope to replace all of this with something beautiful. :-)

The local wiki

The beating heart of my website is the wiki. My wiki pages are all stored in AsciiDoc (wikipedia.org) plaintext format, which is pretty similar to Markdown.

This wiki is edited and navigated locally in Vim with a plugin of my own creation, VViki. VViki is basically a stripped-down VimWiki (another Vim plugin) that natively navigates and edits AsciiDoc files.

To visit (or create!) a page, all I have to do is hit Enter while the cursor is over a word on an existing page. The Backspace key navigates back in the file history. Wiki pages are automatically saved when you leave them. It’s very fast and handy!

Additionally, I’ve written a Bash script called ratlink which works in tandem with a Vimscript function to find pages (to link) and images (to embed) using fuzzy-finding. Here’s the source and write-up for Ratlink.

The wiki is also my private local wiki, where I’ve got various files I don’t publish to the website. (I can even publish to Gopher from my wiki with an AWK script called adoc2gopher.awk but it’s been quite a while since I last did that.)

The static site generator

My entire site is generated from an 80-line Ruby script called make.rb (in this repo). You call it like this:

$ ./make.rb

It is extremely fast (about half a second) by default because it only generates pages which have changed. It determines this with a simple modified date comparison between the .adoc source file and the HTML output!

I don’t do “backlinks” or “greatest hits” or anything like that, so I rarely have a reason to re-generate all pages. But if I need to, I can call it like this:

$ ./make.rb -a

The actual AsciiDoc to HTML conversion is done with the AsciiDoctor library (also Ruby).

The container HTML around the content is contained in template.html (in this repo), which is a Ruby ERB template. It’s under 100 lines, but contains all of the logic to handle different kinds of pages on my site.

The ‘rat’ tool

To quickly edit a specific page or publish changes, I use a multi-tool written in Perl called rat (in this repo).

It’s a real piece of garbage, but it works so well for most things that it has lived for years in its current ridiculous state.

It has a menu when you run it without arguments:

$ rat

Usage:
    rat edit <page_name> (lists partial matches)
    rat feed [<page_name> (lists partial matches)] opens atom.xml
    rat new  <page_name>
    rat dirs             (list all dirs under ratf/src/)
    rat grep             (searches all .adoc files)
    rat lsd              (list all drafts)
    rat pub
    rat card             (open cards/ index)

The things I do most often are rat edit to match a page name and open it in Vim and rat pub (which calls the make.rb script mentioned above and rsyncs the changes up to my VM in the cloud).

I can also kick off rat pub with the ,rp shortcut in Vim, which is what I usually do. (Yeah, Vim calls Perl, which calls Ruby.) I can sort of preview the results locally, but I usually just live-edit pages on the website and preview them there.

You’ll note the completely insane source of the rat feed function that makes entries in my RSS (atom) XML file. The way it works is utterly shameful and is one of the worst things I’ve ever written, but here we are 2.5 years later…

RepoRat

My most recent tool in this list is another Ruby script called reporat. It generates mini-sites for Git repos. (You’re probably reading this via its output right now.)

Here’s the RepoRat repo and here’s my directory of repos published with RepoRat (so far).

I’m super happy with this little tool.

Misc

The ratmyrepo.rb script automatically performs the whole “self-host checklist” process I wrote up on my repos page.

The new-book Ruby script makes new entries for book reviews on my website. I describe the script in my card Interactive Scripts with Vim.

I haven’t run it in a while, but I’ve got a site crawler and link checker written in Ruby called chklnks.rb which works pretty great (though the last time I ran it, I noticed a really crazy number of outbound links that go through more redirects than expected, so I was getting a lot of false negatives).

For a while, I was trying to document every single package that comes with Slackware Linux: Dave’s Slackware Package Blog There is/was a script that generated those pages as I finished them, which I describe in How am I doing this?. (I got kinda bogged down in the colossal coreutils entry and it fizzled out shortly after that).

Another tool that generates content on this site is a Zig Standard Library site generator. Here’s the repo: zstd-browse2 and here’s the output: The Zig Standard Library (the first page is hand-written HTML but all of the linked “.zig” pages are generated by the tool.

There have been other one-offs over the years.

Conclusion

The key to the longevity of all of this is statically generating everything locally and keeping the HTML. I write plenty of HTML by hand, too, just like I did back when I started making web pages by looking at “View Source” on other people’s websites back in the mid-1990s. Here’s a notable example.

(For years, I made various dynamic systems that generated HTML from source documents - the last three generations were written in PHP. Being able to edit pages directly on the website was cool, but I prefer local HTML generation now and can’t really imagine going back.)

For quick page creation and editing, the local wiki is pretty incredible. As a big believer in the “digital gardening” concept, I put “created” and “updated” dates on pretty much everything.

I can make edits on the website from any computer in the house by SSHing into a computer called phobos which you can read about here. Low friction means I’m more likely to make small updates.

Finally, even the crappiest custom software beats “off-the-shelf” every time for making this thing exactly like I want. I don’t have a blog or a wiki or a CMS. I have a website and it does all of those things and more!

For more, check out this cool list of websites built with custom tools: The text and the code go hand in hand (transjovian.org).