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.

Continue reading “Generating a docs website powered by Git & Markdown”

Advertisements