Intro
We’ve got a static HTML site that we host our product documentation on. Our is hosted in Azure Static Web Apps but GitHub pages is a popular option as well (I use it for my AL Test Runner docs). If you’ve got product docs I guess you are hosting them on a static site as well.
We use docfx to generate the site content. I’m not going to post about setting up docfx, building with a pipeline and publishing to Azure or GitHub – there are plenty of details online about that kind of thing already e.g.
- https://dotnet.github.io/docfx/
- https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll
- https://learn.microsoft.com/en-us/azure/static-web-apps/static-web-apps-cli#swa-deploy
This post is about how to maintain the content of the site.
Requirements
Here’s the thing:
- I need the content to be stored in a Git repo so that I can trigger a pipeline to build and publish the site, but
- Consultants who are going to be writing some of the content don’t want to have to care about Git – branches, staging, committing, pushing, pulling – they don’t want to learn any of that
- The docs are written in Markdown – which it is mostly straightforward, but it isn’t always user friendly – especially the syntax to adding  and 
Options
| Option | Pros | Cons |
|---|---|---|
| Writage – add-on for Microsoft Word | Consultants can write the docs with familiar tools and use the add-on to save the document to .md files & linked media | The resulting markdown doesn’t always look the way that it looked in Word. Some of the formatting might be stripped out. You still need to find a way to stage, commit and push the changes to the Git repo as a separate step. |
| Visual Studio Code (+ markdown extensions) | Can easily write the markdown and see a preview of the output side-by-side. Extensions can make it easier to add links between pages, link to media etc. Built in Git support. | You can make it as easy as possible, but in the end VS Code is still a developer’s tool. This doesn’t give a WYSIWYG experience and the consultants do need to understand at least a little about Git. |
…and that is the compromise. Do you have some WYSIWYG designer (Word or something else) that can generate the markdown but then worry about Git? Or do you use something with built-in Git support but is less consultant friendly?
Azure DevOps Wiki
Enter Azure DevOps wikis. They have a WYSIWYG designer with a formatting toolbar to generate the correct markdown and they are a Git repo in the background (cake and eat it 🍰👀).
The formatting toolbar helps you out with formatting, headings, links and so on. You can easily add images and gifs by just copying and pasting into the editor. The image is uploaded DevOps and the markdown syntax inserted automatically.
It also has support for Mermaid diagrams. You need to load the diagram each time you make a change unfortunately, which is a little annoying, but otherwise cool. Just make sure that your static site generator and theme also supports Mermaid (we are using the modern template in docfx).
Pages can be reordered by dragging and dropping them in the navigation. You can also add sub-pages, drag and drop pages to make them sub-pages of other pages.
Sometimes this is a little clunky, but is generally pretty easy to work with.
What you don’t see is that this is updating a .order file which determines the page order to display the pages at the same level in. In this case I will have a .order file for the top-level items and another for the pages under “Product Setup”. We can use that .order file later on to build the navigation for the static site.
Crucially, every time you save or reorder a page, a commit is made to the underlying repository which means you can trigger a pipeline to build and deploy your site automatically. (You could work in separate branches, deploy different branches to different environments, enforce pull requests etc. but I’m not bothering with any of that – part of the goal here is to hide the niceties of Git from the consultants).
Build Pipeline
I won’t walk through all the details of our setup, but now that we have updated markdown content in a new commit we can trigger our build and deploy pipeline (a multi-stage pipeline in Azure DevOps).
Some tips from my experiences:
Building the Table of Contents (toc.yml)
Docfx uses yml to define the navigation that you want the website users to see. Something like this.
items:
- name: Home
href: Home.md
- name: Introduction
href: Intro.md
- name: Setup
items:
- name: Setup Subpage 1
href: Setup/Subpage 1.md
- name: Setup Subpage 2
href: Setup/Subpage 2.md
The wiki repo will have a file structure like this:
C:.
│ .order
│ Home.md
│ Intro.md
│
└───Setup
.order
Subpage1.md
Subpage2.md
so we can work recursively through the folders in the repo, reading the contents of the .order file as we go and converting them to the required format for toc.yml
The .order is simply a plain text file with the names of the pages at that level of the folder structure in their display order.
Home
Intro
Then build the site e.g. docfx build ... and publish to your hosting service of choice.
Batch Commits
Editing the wiki can create a lot of commits. Everytime you save or reorder a page. You probably don’t want to trigger a build for every commit. You can use batch in your pipeline. If a build is already running DevOps will not queue another until it has finished. It will then queue a build for the latest commit and skip all the commits in between.
trigger:
batch: true
Mermaid Syntax
Azure DevOps uses colons for a Mermaid diagram
::: mermaid
...
:::
but docfx needs them as backticks, so I have a task in the pipeline which just does a find replace
```mermaid
...
```
James Pearson 