Documentation … chore or joy, or neither? I’ve been wanting to put the nifty Docsify-This publishing tool made by Paul Hibbitts into play.
Amongst my sprawl of Github projects are the SPLOT WordPress themes each with a rather sprawling in its own rights README file that includes my efforts at splotware documentation (look at this monster).
I had built in my themes a place to include the documentation, via a tab of the themes’ options panel.
I would run the Markdown content of the Readme through a command line pandoc to convert it to HTML, which then required some search and replace to make the remote image links work. This was then all included into this panel with a PHP include command.
To jump to the chase, I have been able to replace this with an iframe that embeds the current version of the README on the fly (currently the entire README but I have a plan scope it). But the key thing is it is done without any of these middling steps.
It worked, but was tedious, and I slipped often in updating it when I made small changes.
The docs were sloppy, doc.
I had been following, not really keeping up, with some impressive dynamic web publishing (including course templates) Paul Hibbitts was sharing via Github. He began sharing was to render markdown content live via this docsify thing made to render markdown content as web pretty versions, on the fly.
From Paul’s earlier efforts, a first experiment was forking a Github repo to here and I was able to make my own site that could render all my SPLOT docs in one site and each one linked to a standalone,linkable version of each one (example, example, example). My base site acts as a “service” that can render any Github markdown as a pretty, even if simple, web page, by passing a URL as a parameter.
What Paul is doing now with this at https://docsify-this.net/ is offering it as a mini web service that saves you the effort of forking and customizing. Plus he seems to be adding new features, display options every other day.
This Web app, built using the magical documentation site generator Docsify and the Docsify Open Publishing Starter Kit, provides a quick way to display Markdown files as standalone Web pages (also perfect for embedding) without needing to setup your own Website. All you need is a publicly available Markdown file and pass that URL to https://docsify-this.net. Try it out below!
https://docsify-this.net
Somewhere recently I read a post about suggestions for more useful/effective software READMEs, and I know I have jammed too much in mine. I have a plan to split out the detailed long documentation into its own separate markdown file, and leave the README as more of an overview of the code. With the flexibility of Docsify-This it will be easy to change my embed to point to a markdown file of just the relevant docs about the theme.
Now this may sound obscure or not all that relevant beyond my Github/SPLOT/techno nattering mumblings (someone’s blog rust is showing). If you maybe look at some of the examples Docsify This and maybe Paul’s template kit, I hope you can see this is a versatile means to put together a small public web site, all for free using Github.
Give it a spin, doc, at https://docsify-this.net/
Featured Image: An image of a noble looking explorer statue inside a book store in Puerto Rico, a wisde documenter indeed. The image Book Explorer flickr photo by cogdogblog shared under a Creative Commons (BY) license was modified by me to include an overlay of the SPLOT logo, same license applies.
