atc-net Markdown Conventions
Apply these conventions when writing, editing, or reviewing markdown files to ensure consistent, readable, and accessible content.
Heading Hierarchy
Use H2 (##) and H3 (###) for document structure. H1 is reserved for the document title (typically generated automatically from metadata or filename) -- never add an H1 inside the body.
If you find yourself reaching for H4 (####) or deeper, that is a signal the document structure is too nested. Restructure by splitting into separate sections or files instead.
## Main Section
Content here.
### Subsection
More detail here.
Lists
Use - for unordered (bullet) lists and 1. for ordered (numbered) lists. Indent nested items with 2 spaces:
- First item
- Nested item
- Another nested item
- Second item
1. Step one
2. Step two
1. Sub-step
Keep list items parallel in grammatical structure -- if one item starts with a verb, they all should.
Code Blocks
Use fenced code blocks (triple backticks) with a language identifier for syntax highlighting. This helps both readers and tooling parse the content correctly:
```csharp
var result = await service.GetDataAsync(cancellationToken);
```
Use inline code (single backticks) for short references to code elements within prose, such as method names, variable names, or file paths.
Links
Use descriptive link text that makes sense out of context -- screen readers often navigate by links alone, so "click here" or "this page" convey no meaning:
<!-- Good -->
See the [contributing guidelines](CONTRIBUTING.md) for details.
<!-- Avoid -->
Click [here](CONTRIBUTING.md) for details.
Ensure all URLs are valid and point to the intended target.
Images
Always include alt text that describes the image content for accessibility. The alt text should convey what the image shows, not just repeat the filename:
Tables
Use markdown tables with pipe (|) syntax. Include a header row and alignment indicators:
| Name | Type | Description |
|------------|----------|----------------------|
| id | integer | Unique identifier |
| status | string | Current state |
Keep columns aligned in the source for readability. For data that would create very wide tables, consider restructuring as a definition list or separate subsections instead.
Whitespace and Line Length
- Insert a blank line before and after headings, code blocks, tables, and lists
- Avoid multiple consecutive blank lines
- Break paragraph text at a reasonable line length (~80-120 characters) to keep diffs clean and source readable
- Do not add trailing whitespace at the end of lines
General Principles
- Consistency: maintain uniform formatting throughout the document -- same heading levels, same list markers, same code fence style
- Accessibility: always provide alt text for images and descriptive text for links
- Readability: keep the raw markdown source clean and easy to scan, not just the rendered output