Markdown Documentation Standards

Markdown Documentation Standards

Standards for creating consistent, accessible, and well-structured markdown documentation. Follow these guidelines to ensure documentation quality across the repository.

General Instructions

• Use ATX-style headings (##, ###) - never use H1 (#) in content (reserved for document title)
• CRITICAL: Limit line length to 120 characters - this is enforced by CI/CD and pre-commit hooks
• Break long lines at natural points (after punctuation, before conjunctions)
• Use LF line endings (enforced by .gitattributes)
• Include meaningful alt text for all images
• Validate with markdownlint before committing
• These standards serve as the canonical style reference for all markdown in this repository

Line Length Guidelines

The 120-character limit is strictly enforced. When lines exceed this limit:

1. Sentences: Break after punctuation (period, comma, em-dash)
2. Lists: Break after the list marker or continue on next line with indentation
3. Links: Break before [ or use reference-style links for long URLs
4. Code spans: If unavoidable, use a code block instead

Example - Breaking long lines:

<!-- BAD: 130+ characters -->

This is a very long line that contains important information about Azure resources and best practices that exceeds the limit.

<!-- GOOD: Natural break after punctuation -->

This is a very long line that contains important information about Azure resources
and best practices that stays within the limit.

Content Structure

Code Blocks

Specify the language after opening backticks for syntax highlighting:

Good Example - Language-specified code block

```bicep
param location string = 'swedencentral'
```

Bad Example - No language specified

```
param location string = 'swedencentral'
```

Mermaid Diagrams

Always include the theme directive for dark mode compatibility:

Good Example - Mermaid with theme directive

​`mermaid
%%{init: {'theme':'neutral'}}%%
graph LR
    A[Start] --> B[End]
​`

Bad Example - Missing theme directive

​`mermaid
graph LR
    A[Start] --> B[End]
​`

Template-First Approach for Workflow Artifacts

MANDATORY for all workflow artifacts:

When generating workflow artifacts, agents MUST follow the canonical templates in .github/skills/azure-artifacts/templates/. Key examples:

All 15 artifact types have corresponding templates. See artifact-h2-reference.instructions.md for the complete heading reference.

Requirements:

1. Preserve H2 heading order: Templates define invariant H2 sections that MUST appear in order
2. No embedded skeletons: Agents must link to templates, never embed structure inline
3. Optional sections: May appear after the last required H2 (anchor), with warnings if before
4. Validation: All artifacts are validated by scripts/validate-artifact-templates.mjs

Enforcement:

• Pre-commit hooks via Lefthook run validation on every commit
• CI validates on PR/push via GitHub Actions
• Auto-fix available: npm run fix:artifact-h2

Visual Styling Standards

MANDATORY: All agent-generated documentation MUST follow the styling standards defined in:

📚 Azure Artifacts Skill

Quick Reference

Callout Types

> [!NOTE]
> Informational - background context

> [!TIP]
> Best practice recommendation

> [!IMPORTANT]
> Critical requirement

> [!WARNING]
> Security/reliability concern

> [!CAUTION]
> Data loss risk or irreversible action

Collapsible Sections

Use for lengthy content (tables >10 rows, code examples, appendix material):

<details>
<summary>📋 Detailed Configuration</summary>

| Setting | Value |
| ------- | ----- |
| ...     | ...   |

</details>

References Section

Every documentation artifact SHOULD include a ## References section at the bottom:

---

## References

> [!NOTE]
> 📚 The following Microsoft Learn resources provide additional guidance.

| Topic      | Link                                            |
| ---------- | ----------------------------------------------- |
| Topic Name | [Display Text](https://learn.microsoft.com/...) |

Lists and Formatting

• Use - for bullet points (not * or +)
• Use 1. for numbered lists (auto-increment)
• Indent nested lists with 2 spaces
• Add blank lines before and after lists

Good Example - Proper list formatting

Prerequisites:

- Azure CLI 2.50+
- Bicep CLI 0.20+
- PowerShell 7+

Steps:

1. Clone the repository
2. Run the setup script
3. Verify installation

Bad Example - Inconsistent list markers

Prerequisites:

- Azure CLI 2.50+

* Bicep CLI 0.20+

- PowerShell 7+

Tables

• Include header row with alignment
• Keep columns aligned for readability
• Use tables for structured comparisons

| Resource  | Purpose            | Example          |
| --------- | ------------------ | ---------------- |
| Key Vault | Secrets management | `kv-contoso-dev` |
| Storage   | Blob storage       | `stcontosodev`   |

Links and References

• Use descriptive link text (not "click here")
• Verify all links are valid and accessible
• Prefer relative paths for internal links

Good Example - Descriptive links

See the [getting started guide](../../docs/getting-started/quickstart.md) for setup instructions.
Refer to [Azure Bicep documentation](https://learn.microsoft.com/azure/azure-resource-manager/bicep/) for syntax details.

Bad Example - Non-descriptive links

Click [here](../../docs/getting-started/quickstart.md) for more info.

Front Matter (Optional)

For blog posts or published content, include YAML front matter:

---
post_title: "Article Title"
author1: "Author Name"
post_slug: "url-friendly-slug"
post_date: "2025-01-15"
summary: "Brief description of the content"
categories: ["Azure", "Infrastructure"]
tags: ["bicep", "iac", "azure"]
---

Note: Front matter fields are project-specific. General documentation files may not require all fields.

Patterns to Avoid

Validation

Run these commands before committing markdown:

# Lint all markdown files
markdownlint '**/*.md' --ignore node_modules --config .markdownlint.json

# Check for broken links (if using markdown-link-check)
markdown-link-check README.md

Maintenance

• Review documentation when code changes
• Update examples to reflect current patterns
• Remove references to deprecated features
• Verify all links remain valid