{"id":13775231,"url":"https://github.com/christosgalano/bicep-docs","last_synced_at":"2026-01-29T10:10:57.766Z","repository":{"id":218983621,"uuid":"738944486","full_name":"christosgalano/bicep-docs","owner":"christosgalano","description":"bicep-docs is a command-line tool that generates documentation for Bicep templates.","archived":false,"fork":false,"pushed_at":"2026-01-25T19:49:55.000Z","size":1360,"stargazers_count":41,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-26T11:04:17.162Z","etag":null,"topics":["bicep","cli","documentation-generator","go","infrastructure-as-code"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/christosgalano.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-01-04T12:11:26.000Z","updated_at":"2026-01-25T19:49:59.000Z","dependencies_parsed_at":"2024-01-29T23:47:51.234Z","dependency_job_id":"e0590d64-2cd6-476d-847a-9119f121cac9","html_url":"https://github.com/christosgalano/bicep-docs","commit_stats":null,"previous_names":["christosgalano/bicep-docs"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/christosgalano/bicep-docs","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christosgalano%2Fbicep-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christosgalano%2Fbicep-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christosgalano%2Fbicep-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christosgalano%2Fbicep-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/christosgalano","download_url":"https://codeload.github.com/christosgalano/bicep-docs/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christosgalano%2Fbicep-docs/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28875450,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T09:47:23.353Z","status":"ssl_error","status_checked_at":"2026-01-29T09:47:19.357Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bicep","cli","documentation-generator","go","infrastructure-as-code"],"created_at":"2024-08-03T17:01:35.630Z","updated_at":"2026-01-29T10:10:57.738Z","avatar_url":"https://github.com/christosgalano.png","language":"Go","funding_links":[],"categories":["Community"],"sub_categories":["Community Repositories"],"readme":"# bicep-docs\n\n[![ci](https://github.com/christosgalano/bicep-docs/actions/workflows/ci.yaml/badge.svg?branch=main\u0026event=push)](https://github.com/christosgalano/bicep-docs/actions/workflows/ci.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/christosgalano/bicep-docs)](https://goreportcard.com/report/github.com/christosgalano/bicep-docs)\n[![Go Reference](https://pkg.go.dev/badge/github.com/christosgalano/bicep-docs.svg)](https://pkg.go.dev/github.com/christosgalano/bicep-docs)\n[![Github Downloads](https://img.shields.io/github/downloads/christosgalano/bicep-docs/total.svg?cacheSeconds=3600)](https://github.com/christosgalano/bicep-docs/releases)\n\n![bicep-docs](assets/images/main-extra-small.png)\n\n## Table of contents\n\n- [Description](#description)\n- [Installation](#installation)\n- [Requirements](#requirements)\n- [Usage](#usage)\n- [Contributing](#contributing)\n- [License](#license)\n\n## Description\n\n**bicep-docs** is a command-line tool that generates documentation for Bicep templates.\n\n## Installation\n\n### Homebrew\n\n```bash\nbrew tap christosgalano/christosgalano\nbrew install bicep-docs\n```\n\n### Chocolatey\n\n```bash\nchoco install bicep-docs\n```\n\n### Go\n\n```bash\ngo install github.com/christosgalano/bicep-docs/cmd/bicep-docs@latest\n```\n\n### Binary\n\nDownload the latest binary from the [releases page](https://github.com/christosgalano/bicep-docs/releases/latest).\n\n## Requirements\n\nTo run bicep-docs, either the Azure CLI or the Bicep CLI must be [installed](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install).\n\n| CLI   | Minimum Required Version |\n| ----- | ------------------------ |\n| Azure | 2.77.0                   |\n| Bicep | 0.38.3                   |\n\n## Usage\n\nbicep-docs is a command-line tool that generates documentation for Bicep templates.\n\nGiven an input Bicep file or directory, it parses the file(s) and generates corresponding documentation in Markdown format.\n\nThis can be used to automatically create and update documentation for your Bicep templates.\n\nIf the input is a directory, then for each `main.bicep` it will generate a `README.md` in the same directory. This happens recursively for all subdirectories.\n\nIf the input is a Bicep file, the output must be a file; otherwise, an error will be returned.\n\nThe default value for the output is `README.md`, relative to the directory where the command is executed.\n\n**CAUTION:** If the Markdown file already exists, it will be **overwritten**.\n\n### Arguments\n\nRegarding the arguments `--include-sections` and `--exclude-sections`, the available sections are: `description`, `usage`, `modules`, `resources`, `parameters`, `udfs`, `uddts`, `variables`, `outputs`.\n\nThe default sections ordered are `description,usage,modules,resources,parameters,udfs,uddts,variables,outputs`. The default input for`--exclude-sections` is `''`.  This ensures backward compatibility with the previous version.\n\nThe order of the sections is respected when including them.\n\nWhen excluding sections, the result will be the default sections minus the excluded ones (e.g. `--exclude-sections description,usage` will include `modules,resources,parameters,udfs,uddts,variables,outputs` in that order).\n\nBoth arguments cannot be provided at the same time, unless the `--include-sections` argument is the same as the default sections (e.g. `--include-sections description,usage,modules,resources,parameters,udfs,uddts,variables,outputs`).\n\nThe `--show-all-decorators` flag can be used to include additional columns in the documentation tables showing constraint information from Bicep decorators (allowed values, min/max constraints, exportable status, etc.). By default, these details are hidden to keep the documentation concise.\n\n### Example usage\n\nParse a Bicep file and generate a Markdown file:\n\n```bash\nbicep-docs --input main.bicep --output readme.md\n```\n\nParse a Bicep file and generate a README.md file in the same directory:\n\n```bash\nbicep-docs -i main.bicep\n```\n\nParse a directory and generate a README.md file for each main.bicep file with verbose output:\n\n```bash\nbicep-docs -i ./bicep -V\n```\n\nParse a Bicep file and generate a README.md excluding the user-defined sections:\n\n```bash\nbicep-docs --input main.bicep --exclude-sections udfs,uddts\n```\n\nParse a Bicep file and generate a README.md including only the resources and modules in that order:\n\n```bash\nbicep-docs ---input main.bicep --include-sections resources,modules\n```\n\nParse a Bicep file and generate comprehensive documentation with all decorator information:\n\n```bash\nbicep-docs --input main.bicep --show-all-decorators\n```\n\nMore examples can be found [here](examples).\n\n### Documentation format\n\nThe documentation has the following format:\n\n```markdown\n# module name | file name\n\n## Description\n\n...\n\n## Usage\n\n...\n\n## Modules\n\ntable of modules\n\n## Resources\n\ntable of resources\n\n## Parameters\n\ntable of parameters\n\n## User Defined Data Types (UDDTs)\n\ntable of UDDTs\n\nFor every UDDT u with properties, a sub-section is created:\n\n### u\n\ntable of properties\n\n...\n\n## User Defined Functions (UDFs)\n\ntable of UDFS\n\n## Variables\n\ntable of variables\n\n## Outputs\n\ntable of outputs\n\n```\n\n### Handling of Loops\n\nThe tool follows these conventions when documenting resources, modules, variables, and outputs that use copy/loop constructs:\n\n**Resources and Modules:**\n- For resource/module arrays (using copy loops), only the base resource/module is documented with its symbolic name\n- The documentation shows the type and description once, rather than documenting each iteration\n- Example:\n  ```bicep\n  resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' = [for i in range(0, 5): {...}]\n  module appService 'br/modules:app:v1' = [for env in environments: {...}]\n  ```\n  Each is documented as a single entry in their respective tables\n\n**Variables and Outputs:**\n- For array comprehension variables/outputs (using copy), the item is documented once with its description\n- Both the array item and its transformed version are included in the documentation\n- Example:\n  ```bicep\n  var storageConfigs = [for i in range(0, length(locations)): {...}]\n  var ipFormatWithDuplicates = [for this in storageConfigs: {...}]\n\n  output resourceIds array = [for i in range(0, length(locations)): storageAccount[i].id]\n  output names array = [for config in storageConfigs: config.name]\n  ```\n  Each appears as a single entry in their respective tables\n\nThis approach keeps the documentation clean and focused on the logical structure rather than implementation details.\n\n### Folder structure\n\nThis tool is extremely useful if you are following this structure for your Bicep projects:\n\n```text\n.\n├── bicep\n│   │\n│   ├── modules\n│   │   ├── compute\n│   │   │   ├── main.bicep\n│   │   │   └── README.md\n│   │   └── ...\n│   │\n│   ├── environments\n│   │   ├── development\n│   │   │   ├── main.bicep\n│   │   │   ├── main.bicepparam\n│   │   │   └── README.md\n│   │   └── ...\n```\n\n## Contributing\n\nInformation about contributing to this project can be found [here](CONTRIBUTING.md).\n\n## License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristosgalano%2Fbicep-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchristosgalano%2Fbicep-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristosgalano%2Fbicep-docs/lists"}