# 1564 Markdowninstructions 56ad3ac4
> Documentation and content creation standards for markdown files
- Skill: `tools-only/1564-markdowninstructions-56ad3ac4` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add tools-only/1564-markdowninstructions-56ad3ac4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/1564-markdowninstructions-56ad3ac4/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tools-only (https://skillmd.com/u/tools-only)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/tools-only/1564-markdowninstructions-56ad3ac4
---
# 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:**
```markdown
This is a very long line that contains important information about Azure resources and best practices that exceeds the limit.
This is a very long line that contains important information about Azure resources
and best practices that stays within the limit.
```
## Content Structure
| Element | Rule | Example |
| ----------- | ---------------------------------------- | ---------------------------------------------------------- |
| Headings | Use `##` for H2, `###` for H3, avoid H4+ | `## Section Title` |
| Lists | Use `-` for unordered, `1.` for ordered | `- Item one` |
| Code blocks | Use fenced blocks with language | ` ```bicep ` |
| Links | Descriptive text, valid URLs | `[Azure docs](https://...)` |
| Images | Include alt text | `` |
| Tables | Align columns, include headers | See examples below |
## Code Blocks
Specify the language after opening backticks for syntax highlighting:
### Good Example - Language-specified code block
````markdown
```bicep
param location string = 'swedencentral'
```
````
### Bad Example - No language specified
````markdown
```
param location string = 'swedencentral'
```
````
## Mermaid Diagrams
Always include the theme directive for dark mode compatibility:
### Good Example - Mermaid with theme directive
```markdown
`mermaid
%%{init: {'theme':'neutral'}}%%
graph LR
A[Start] --> B[End]
`
```
### Bad Example - Missing theme directive
```markdown
`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:
| Artifact | Template | Producing Agent |
| ------------------------------- | -------------------------------------------------- | --------------- |
| `01-requirements.md` | `01-requirements.template.md` | requirements |
| `02-architecture-assessment.md` | `02-architecture-assessment.template.md` | architect |
| `04-implementation-plan.md` | `04-implementation-plan.template.md` | bicep-plan |
| `06-deployment-summary.md` | `06-deployment-summary.template.md` | deploy |
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](../skills/azure-artifacts/SKILL.md)**
### Quick Reference
| Element | Usage | Example |
| -------------- | ------------------- | ---------------------------------------------- |
| Callouts | Emphasis & warnings | `> [!NOTE]`, `> [!TIP]`, `> [!WARNING]` |
| Status Emoji | Progress indicators | ✅ ⚠️ ❌ 💡 |
| Category Icons | Resource sections | 💻 💾 🌐 🔐 📊 |
| Collapsible | Long content | `...
...
📋 Detailed Configuration
| Setting | Value |
| ------- | ----- |
| ... | ... |
```
### References Section
Every documentation artifact SHOULD include a `## References` section at the bottom:
```markdown
---
## 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
```markdown
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
```markdown
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
```markdown
| 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
```markdown
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
```markdown
Click [here](../../docs/getting-started/quickstart.md) for more info.
```
## Front Matter (Optional)
For blog posts or published content, include YAML front matter:
```yaml
---
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
| Anti-Pattern | Problem | Solution |
| ----------------------- | ---------------------------- | -------------------------- |
| H1 in content | Conflicts with title | Use H2 (`##`) as top level |
| Deep nesting (H4+) | Hard to navigate | Restructure content |
| Long lines (>120 chars) | Poor readability, lint fails | Break at natural clauses |
| Missing code language | No syntax highlighting | Specify language |
| "Click here" links | Poor accessibility | Use descriptive text |
| Excessive whitespace | Inconsistent appearance | Single blank lines |
## Validation
Run these commands before committing markdown:
```bash
# 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