Introducing makedocs.io

The Making Tools Addiction Continues

2021-10-12

Why

You don't want to make project documentation but the reasons that you should are there. Pick the scenario because there are many of them. Over the years I have said and heard the phrase, "we should set up a quick doc site for this" and some else will say "yes we should" and it goes on the backlog to live forever.

These things are not hard to do but it seems, at least in my journey, that there is just enough friction to where it doesn't happen. Other things to work on always come up.

I like building tools so I built a little bit of stuff to help me in this situation. I also like things that are easy to install and seemingly 'just work'. Lastly I like those tools that can be dropped into a repo directly from the internet. I do this with dotnetzero, azurepipelineagent, and likely the next itch that needs a scratch. The pattern is to get an (hopefully) somewhat easy to remember url. Visit that url in the browser and you get the site, hit the same url with your terminal and you get the script. Thanks user-agent sniffing!

My Initial Solution Draft

Static site generators are popular. It's a build time construct for html content versus having a web server that handles content from some sort of persistence mechanism. For this little project that I cooked up while waiting for kids soccer, volleyball and driving practices called makedocs.io I am initially standing up toolchain for hugo and mkdocs.

With that I created a set of scripts that will invoke the generator's new site function to get just the bare minimum files created that can then be packaged up and then downloaded to the target repo as part of makedocs.io running in your terminal. Each package also will unpack a Github Actions or Gitlab Pipeline file to add or append to your local repo so that you can hopefully get content going for your project quickly.

Currently I have it working with bash and Powershell and at the moment the build tool from Christmas past is a Makefile. Yes Makefile in the year 2021 :| I'll get a psake/invoke-build support added after a bit because I'd like my build toolchain to be xplat.

So head over to makedocs.io and give a test drive and let me know if it has any potential value.