Azure Checklists - Transform Checklists JSON to Markdown

The github.com/Azure/review-checklists repository is widely used by Microsoft and customers alike for Cloud Architecture Reviews.

Challenge

The checklist data is hardcoded in JSON, which is cumbersome for community contribution. For example, many engineers copy and pasted guids and did not understand they were required for generating the Excel file.

Solution

Transforms JSON data from review checklists JSON format into markdown front matter.

Advantages of Markdown over JSON

• Use rich text in body, incl. bold, lists, etc.
• Leverage Nuxt Content's built-in search functionality
• No need to generate GUIDs (each item uses its file path as unique key)
• Native integration with Nuxt for static site generation with pre-rendering for better performance

Before - JSON for Excel

N.B. original guid was required for integration with Microsoft Excel and had to be manually generated by the engineer contributing to the project.

{
  "category": "Management",
  "subcategory": "Data Protection",
  "text": "Enable cross-region replication in Azure for BCDR with paired regions.",
  "waf": "Reliability",
  "guid": "7ea02e1c-7166-45a3-bdf5-098891367fcb",
  "id": "F02.01",
  "severity": "Medium",
  "link": "https://learn.microsoft.com/azure/reliability/cross-region-replication-azure",
  "training": "https://learn.microsoft.com/training/modules/provide-disaster-recovery-replicate-storage-data/"
}

After - Markdown for Rich Content

Leveraging markdown in combination with a web application, opens opportunity for rich content with images, etc. that can more effectively illustrate technical concepts and nuanaces to customers.

---
category: "Management"
subcategory: "Data Protection"
text: "Enable cross-region replication in Azure for BCDR with paired regions."
waf: "Reliability"
guid: "7ea02e1c-7166-45a3-bdf5-098891367fcb"
id: "F02.01"
severity: "Medium"
link: "https://learn.microsoft.com/azure/reliability/cross-region-replication-azure"
training: "https://learn.microsoft.com/training/modules/provide-disaster-recovery-replicate-storage-data/"
---

# Advantage of Markdown

Opens opportunity for rich content including links, images, etc.

Notes:

• The single JSON file into covnerted to multiple markdown files - 1 file per checklist item.
• guid becomes a legacy metadata that is preserved in front matter.