Blog

PSDocs for azure bicep

PSDocs for Azure Bicep: Automate Your IaC Documentation!💪🏻

Introduction

Let’s be honest: writing documentation is usually the least exciting part of working with Infrastructure as Code (IaC). But what if generating clean, structured, and human-readable documentation was as simple as running a single command? That’s exactly what PSDocs enables — especially when working with Azure Bicep.

In this guide, we’ll walk you through how to automate the generation of documentation for your Bicep files using PSDocs. We’ll build a small PowerShell function that handles everything from compiling Bicep to generating a README.md file based on the ARM template. By the end, you’ll have a fully functional workflow to document your Bicep code automatically — saving you time and improving collaboration across teams.

Prerequisites

Before you begin, make sure you have the following in place:

  • PowerShell 7.x installed on your system

  • PSDocs.Azure module installed

  • Azure CLI and Bicep CLI installed and configured

  • Basic understanding of Bicep and ARM templates

  • A sample Bicep file (main.bicep) with proper parameter metadata

  • Optional: A metadata.json file to enrich the generated documentation

Step-by-Step Guide

1. Install the PSDocs Module

Before generating any documentation, you need to install the PSDocs and PSDocs.Azure modules. These are essential for transforming ARM templates into markdown documentation.

# Install PSDocs and the Azure-specific ruleset
Install-Module -Name PSDocs -Scope CurrentUser -Force
Install-Module -Name PSDocs.Azure -Scope CurrentUser -Force

âś… Tip: You only need to do this once per machine.

2. Create the PowerShell Documentation Function

Let’s automate the process with a custom PowerShell function called Invoke-BicepDocumentation. This function does three things:

  1. Builds the Bicep file into an ARM template

  2. Uses PSDocs to generate the documentation

  3. Saves the output in a specified folder

Here’s what it looks like:

function Invoke-BicepDocumentation {
    param (
        [string]$bicepFilePath,
        [string]$outputFolderPath
    )

    # Build the Bicep file into ARM JSON
    $templateFile = "$($outputFolderPath)/template.json"
    bicep build $bicepFilePath --outfile $templateFile

    # Generate README.md using PSDocs
    Invoke-PSDocument `
        -Module PSDocs.Azure `
        -InputObject $templateFile `
        -OutputPath $outputFolderPath `
        -Option @{
            'PSDocs.Azure.UseMetadataFile' = $true
        }
}

Run the function like this:

Invoke-BicepDocumentation -bicepFilePath "./main.bicep" -outputFolderPath "./markdownFiles"

This will generate a README.md inside the markdownFiles directory.

3. Add metadata for Better Results

To make the documentation more informative, include a metadata.json file in your project directory. This file allows you to define default values like title and description that are automatically injected into the output.

Example metadata.json:

{
  "metadata": {
    "title": "Example Bicep Module",
    "description": "This module deploys an example Azure resource."
  }
}

When you use Invoke-PSDocument, the module will pull these values and add them to your README output, giving you rich context in your final documentation.

Visuals and Diagrams

Here are a visual for my main.bicep to help you understand how everything connects:

kvbicep

🧾 Output Sample

Here’s a snapshot of the auto-generated README.md:

PsDocs

Conclusion

By using PSDocs with Azure Bicep, you’ve unlocked a clean, repeatable way to generate documentation directly from your infrastructure code. Not only does this improve clarity for teams consuming your modules, but it also ensures your documentation stays up to date — no manual edits required.

What’s Next?

  • Try integrating this workflow into your CI/CD pipelines

  • Explore advanced PSDocs templates and output formats

  • Learn about other tools like DocFX and Markdownlint for further documentation automation

⚠️ Common Mistake: Don’t forget to compile your Bicep file before passing it to PSDocs. It only works with ARM templates, not raw Bicep!

Let automation do the boring work — and let your documentation shine. ✨

You are currently viewing PSDocs for Azure Bicep: Automate Your IaC Documentation! 💪🏻