# Rat-Tools

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

<img src="/repos/og_imgs/rat-tools.jpg" alt="drawing of a cute rat with a hammer" style="float: right; margin: 1em;">

This repo contains and describes some of the specialized tools I use to maintain my website,
<a href="http://ratfactor.com">ratfactor.com</a>.

They're uniquely awful, which is a classic case of
<a href="https://en.wiktionary.org/wiki/the_cobbler%27s_children_are_the_worst_shod">"the cobbler's children are the worst shod"</a>
(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 
<a href="https://en.wikipedia.org/wiki/AsciiDoc">AsciiDoc</a>
(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,
<a href="http://ratfactor.com/repos/vviki/">VViki</a>.
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 
<a href="https://ratfactor.com/cards/ratlink">Ratlink</a>.

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
`rsync`s 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
<a href="http://ratfactor.com/repos/reporat/">RepoRat repo</a>
and here's my directory of
<a href="http://ratfactor.com/repos/">repos published with RepoRat</a> (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
<a href="http://ratfactor.com/repos/">my repos page</a>.

The `new-book` Ruby script makes new entries for
<a href="http://ratfactor.com/b/">book reviews on my website</a>. I describe the script in my card
<a href="http://ratfactor.com/cards/interactive-vim">Interactive Scripts with Vim</a>.

I haven't run it in a while, but I've got a site crawler and link checker
written in Ruby called
<a href="http://ratfactor.com/repos/chklnks.rb/">chklnks.rb</a>
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:
<a href="http://ratfactor.com/slackware/pkgblog/index">Dave's Slackware Package Blog </a>
There is/was a script that generated those pages as I finished them,
which I describe in
<a href="http://ratfactor.com/slackware/pkgblog/how">How am I doing this?</a>.
(I got kinda bogged down in the colossal
<a href="http://ratfactor.com/slackware/pkgblog/coreutils">coreutils</a> 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:
<a href="http://ratfactor.com/repos/zstd-browse2/">zstd-browse2</a>
and here's the output:
<a href="http://ratfactor.com/zig/stdlib-browseable2/">The Zig Standard Library</a>
(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.
<a href="https://ratfactor.com/forth/the_programming_language_that_writes_itself.html">Here's a notable example.</a>

(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
<a href="https://ratfactor.com/setup2">here</a>.
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:
<a href="https://transjovian.org/view/web-sites/index">The text and the code go hand in hand</a>
(transjovian.org).