The Azure Citadel site is hosted in GitHub pages. This allows contributors to documentation using standard markdown.

Once committed to the main repository then the Jekyll engine takes the markdown and then renders it as the static HTML you see on Azure Citadel.


The content on Citadel is only ever intended to complement the official Azure documentation. In the UK we use it actively to help partners achieve a step change in their Azure capabilities as we build new practices and propositions. But as a community site it has proved popular, especially when using lengthier labs to combine various Azure and open source products and tooling.

Much of the content is hosted directly within the repository, but we also have a number of contributors who maintain the labs in their own repositories (where they have full read/write access) and then create landing pages with Azure Citadel as another channel for users to discover those labs.

As of January 2019 we have moved to a new site theme, so we will start by covering off on some of the reasons for that change. If you are interested in contributing then this guide will go through the various areas. Please use the comments area


The new guide will cover the following areas:

Page Description
Minimal Mistakes Summary of new features with the Minimal Mistakes theme
Categories New categorisation and content curators
GitHub Overview of the GitHub workflow
Cloning How to fork the repository and clone it locally within vscode
Authors If you are a new contributor to Citadel then see how to add your details
Content Guidance on structuring your content
Single Page How to configure content to generate a single page
Front Matter How to configuring the Front Matter section at the top of the .md files
Markdown A few markdown basics, including links, images and videos, plus alternatives
Multi Page How to create multi page content and custom navigation
Reviewing How to check your content before submitting for the Pull Request

Leave a comment