Generating a docs website powered by Git & Markdown

Did you know I’m a huge fan of the Microsoft / Azure docs? Did you also know that the docs websites are powered by GitHub repositories? Let that one sink in… So you can leverage the same way you collaborate on code, work on publishing documentation?!? How awesome is that!

After a bit of looking around, it appears DocFX is actually powered to do this. I don’t know if this is the tool used behind the docs website. Though there seem to be a lot of similarities. Anyhow, today’s post will be a quick walkthrough on how to setup DocFX with VSTS to publish your GitHub driven repo to an Azure Web App.

Be sure to install DocFX on your dev station to initialize the repository. This is done by running “docfx init -q” inside of your repository.

Afterwards do your typical Git magic to sync your local version with GitHub (or equivalent). Now you’ll have a dummy skeleton ready for usage, and you can now structure it to your liking! My effort is going into making docs for VMchooser.

If we would now run “docfx docfx.json”, it will generate a static website into the directory “_site”. Which is great as such… Though the real power lies in automating this process.

Setting up a build

Let’s create a Build for our docs. Every time a change is done to the repository (continuous integration), we’ll do a build that’ll publish an artifact. In terms of build steps ;

Install/Upgrade Chocolatey on our build agent (if needed)

Install the docfx package (if needed)

Run docfx

Archive the static website (_site folder)

Publish that archive

And if we let the beast do its thing… Then we see that the website gets generated/archived/published!

Publishing our docs website

Next up, the release part of our flow. As usual, we’ll be doing a continuous deployment (CD) too. So every time a new artifact has been published, we’ll release it. The release process here is very simple; download the artifact and use the zip to deploy to an App Service.

And as before, if we let the beast do its thing… The release will do what the release should do.

And with the combination of the mark down (.md) files and the table-of-contents (toc.yml), you’ll be able to create a nicely structured website!

Closing Thoughts

The above can be setup in give or take 15 minutes. It provides a clean & automated manner to publish your docs. Where on the backend side of things, you can collaborate on this content like would collaborate on code. So not providing docs shouldn’t be blocked by technical capabilities anymore! 😉

Up in the Clouds

Views are my own

The content of this blog will, at all times, portray my own views. At no time will this reflect the views of the organization I am linked to. Neither can the information provided be used as support statement.