Generating a docs website powered by Git & Markdown

Introduction

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.

 

So what will we be needing?

Ingredients

  • GitHub repository
  • VSTS Account
  • Azure App Service
  • A tool to do the conversion : DocFX
  • Chocolatey to install DocFX

 

Initialize the repository

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 that’s publish our website!

What’s the experience from VS?

So how does that look from my dev machine? I’ve installed a mark down editor extension, which does what advertised… πŸ™‚

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! πŸ˜‰

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.