GTFM (Generate the Friendly Manual)

The Zsh Manual is already friendly; I just decided to make it more hospitable by publishing an mdBook version. I endeavored to automate this with a script and deploy the mdBook via Netlify. The result can be viewed here: https://zsh-manual.netlify.app

I started out writing a Python script, but after some progress I realized that the task could be done more efficiently with my homies Bash, Sed, and Find, though I kept the bit of Python code that generates the SUMMARY.md file.

The script does the following 8 tasks:

Downloads and extracts the tar.gz archive of the Zsh Manual from their website

Removes some unneeded files

Removes some HTML noise using Sed

Renames the file extensions from .html to .md

Converts html to GitHub-flavored Markdown using Pandoc

Moves the resulting markdown files to the temporary mdBook src directory

Generates a table of contents for each file using DocToc.

Calls a Python script to generate the SUMMARY.md by scraping the original Zsh Manual’s table of contents.

There are probably some minor issues that could be found by perusing the mdBook but all in all the content seems to have transferred over nicely. The only parts that are missing are the indexes from the original Zsh Manual–their HTML structure doesn’t lend itself well to Markdown–but I reckon there is little need for them now with mdBook’s search feature.

UPDATE: I now use a Perl script to do all of these tasks.

Original Zsh Manual

Modernized Zsh Manual

https://github.com/hyperreal64/zsh-manual-mdBook

END

Last updated: 2021-11-18

Gemlog archive

Back to hyperreal.coffee