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