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! 😉
Karim Vaes 
all the links on website point to you website.
Not sure to what you are referring…
Because you are using a picture for the Use DocFX steps
Exporting a pipeline in an anonymous manner isn’t that straightforward. So I post the details of each task, in order to enable you to replicate the result. 😉
Missing the steps how to get the chocolatey task in there. Installed the ChocolateyTools with Marketplace but still don’t see the chocolatey task.
Futher i like you blog about this topic.
Hope you can help me futher.
This is the extension I use for it ; https://marketplace.visualstudio.com/items?itemName=jungeriusit.jungit-choco&targetId=71f23217-ec55-4ce4-97ff-078b158867aa&utm_source=vstsproduct&utm_medium=ExtHubManageList
Yes, that i have also installed, but that 2 steps that you mention you can only use in the release pipeline and not in the build pipeline.
Hi Kvaes, i’m using docfx for my user documentation, in azure dev ops where i can find the build pipeline for docfx?
There is no template for it. Just mimick the same things I did. 😉
this is done only for one repo if want to do it another have to do it all steps again
how to use docfx where i have my source docfx.json from github or devops repo url?
which way is feasible to use exe or nuget ?
i will pass different repo url every time which will have docfx.json
I tried –
1.docfx.exe but it won’t take http url as a input paramter it only run on local VM is not best solution for exe.
2.docker image but not a best approch either
3.nuget but how to use it as a central project where i will pass repo url and generate doc
kindly help me with approach.
or how to setup a build pipeline where take repo url as input as do all above process as you mention in blog.