home

<BEGIN>

Downloading Documentation for Fun and Profit Because You Need an Offline Copy

Having no internet sucks, so use it while you have it. Here are my personal favorite ways of making websites (mostly code documentation and some articles so far) available for offline use.

The previous method works fine for an application that generates/loads actual files. However, some web applications make the unfortunate decision to dynamically replace the contents of the webpage based on the URL without ever actually making an HTTP request. All of the contents are bundled into a WASM binary or minified Javascript. The Zig StdLib docs make this choice, and I despise it. Yes yes, you’d like to show off Zig’s suitability for writing WebAssembly. That’s very nice. Can I have a normal website please? Like, serving a document is what HTTP is for.

No, you can’t have a normal website. It’s time to pull up your pants and write some JavaScript, most likely using the Playwright library. This will use headless Chromium or Firefox (your choice) to emulate a browser to the unsuspecting website, allowing you to read the fucking page markup as Berners-Lee intended.

Alright, you have your documentation. Now you’d like to read it. Unfortunately, someone has decided that this document should feature black text on a white background, and it’s midnight. Reverse that scenario if you hate dark mode. Also, you’d like a standardized format to read everything in. I don’t know. It is literally almost midnight here and I’m tired.

A combination of JSDOM and Mozilla’s freestanding version of Readability are the best options I know of here. (Did you know Mozilla published this as a standalone library? What the fuck?) Pandoc, depending on your desired output format. That’s all you need unless you have one very specific use case. You need not read on.

…

…

Ok. A while ago, I was converting some books to markdown. I think I was mostly using epubs, so it “shouldn’t” have been that hard. After wrangling with some frankly atrocious JavaScript libraries (seriously, problems ranging from documentation that seems to be Just Wrong to the worst way to pass arguments to a function I have ever seen in my life. In the same library.) I managed to get markdown output that looked reasonably good. Except I was reading it in Vim, and the internal markdown links just? didn’t work? Like, an anchor tag to an element with an ID decided that it was really pointing at another anchor tag with an href of #10. So I wrote a little bit of… middleware? I guess? To add UUIDs to link names. And that works, and if you want to read the code you can be my guest.

Another addendum that I don’t think fits anywhere else, though it technically inspired this whole post: devdocs.io lets you keep documentation offline (ironically using some kind of SPA). This is wonderful. They do not, however, seem to let you look at the documentation for anything other than the “stable” version. This is a problem with Zig. Zig changes constantly, and there’s an entire namespace (async) that’s been removed since 0.11. Don’t worry, though, because devdocs doesn’t… seem to have Zig’s StdLib documentation in the first place? They just have the language reference. Which is, I suppose, an interesting alternative to Zig’s approach of including a copy of the StdLib documention in your Zig download… but not the language reference. Lol. Lmao. So as of this writing (April 13 by 10 seconds) you can have an offline version of the 0.11 language reference and an offline version of the 0.12 StdLib docs, but not the other half of either. Unless you download some webpages yourself. Oh well.

1: uhhhh for those of you who also use the Fish shell, here’s a script I wrote? The rest of you are SOL I guess.

<BEGIN>