AWS Logo
Menu
Cross-Platform Git Publishing

Cross-Platform Git Publishing

Publish a website from GitHub sources using Azure Pipelines.

websitepublicationgithubazure-devopspipeline
Ahmad Ferdaus Abd Razak
Published Apr 10, 2025
This one isn't strictly related to AWS, but I think it was an interesting experiment nonetheless.
Recently, I became part of a group tasked with creating a documentation wiki publishing solution. The requirements:
  1. The documentation source files must live in GitHub as Markdown or DOCX. If they are DOCX, convert and pubilsh them as Markdown.
  2. The pipelines must run in Azure DevOps (this division was made long ago, for some reason).
  3. Documentations from multiple teams in mulitiple GitHub source repositories must be published in a single wiki site.
  4. The site is published on GitHub Pages using Jekyll as the HTML content generator.
  5. Authenticate from Azure DevOps to GitHub securely.
The automation capabilities:
  1. Convert DOCX files to Markdown with image and Table-of-Contents processing.
  2. Insert Jekyll front matter if none exists in output Markdown files using details parsed from the source.
  3. Templatize and parameterize pipelines so they can be reused easily by multiple teams without hosting the source.
  4. Publish final outputs to the wiki site and back to source repositories for future updates.
  5. Preview HTML during Pull Request from Markdown outputs.
The solution diagram:
Solution diagram
Solution diagram
After a considerable amount of wrangling with regular expressions, Base64 tag parsing and encoding, Jekyll-GitHub Pages quirks, and parameter tracking / passing through the entire workflow, the solution is made available via GitLab. It uses Python, BASH, and Azure Pipelines YAML under the hood. To create an article on the wiki site, users must allow the pipeline identity access to their source repositories and use the "seed" pipelines to trigger the process when they submit Markdown and / or DOCX files to their repositories.
 

Comments