|
| 1 | +--- |
| 2 | +applyTo: '**/*.md' |
| 3 | +description: Markdown style guidelines for consistency across documentation. |
| 4 | +--- |
| 5 | + |
| 6 | +# Markdown Style Guidelines |
| 7 | + |
| 8 | +This document defines the Markdown style guidelines for all Markdown files in this repository. These rules follow common Markdown linter best practices and ensure consistency across documentation. |
| 9 | + |
| 10 | +## Headings |
| 11 | + |
| 12 | +- Use ATX-style headings (`#`) instead of Setext-style (underlines) |
| 13 | +- Include a space after the hash marks: `# Heading` not `#Heading` |
| 14 | +- Use only one top-level heading (`#`) per document |
| 15 | +- Do not skip heading levels (e.g., don't go from `#` to `###`) |
| 16 | +- Surround headings with blank lines (one before, one after, excluding the first heading in the document unless preceded by frontmatter) |
| 17 | +- Do not use trailing punctuation in headings (no periods, colons, etc.) |
| 18 | +- Use sentence case for headings unless referring to proper nouns or code identifiers |
| 19 | + |
| 20 | +**Good:** |
| 21 | + |
| 22 | +```markdown |
| 23 | +# Main heading |
| 24 | + |
| 25 | +## Subsection |
| 26 | + |
| 27 | +### Details |
| 28 | +``` |
| 29 | + |
| 30 | +**Bad:** |
| 31 | + |
| 32 | +```markdown |
| 33 | +#No space after hash |
| 34 | +### Skipped level 2 |
| 35 | +## Heading with period. |
| 36 | +``` |
| 37 | + |
| 38 | +## Lists |
| 39 | + |
| 40 | +- Use consistent list markers throughout the document (`-` for unordered, `1.` for ordered) |
| 41 | +- Do not add blank lines between list items (unless item contains multiple paragraphs) |
| 42 | +- Indent nested lists by 2 spaces for unordered, 3 spaces for ordered |
| 43 | +- Use `1.` for all ordered list items (auto-numbering) or number them sequentially |
| 44 | +- Surround lists with blank lines (one before, one after) |
| 45 | +- Use `-` for unordered lists (not `*` or `+`) |
| 46 | + |
| 47 | +**Good:** |
| 48 | + |
| 49 | +```markdown |
| 50 | +Here is a list: |
| 51 | + |
| 52 | +- First item |
| 53 | +- Second item |
| 54 | +- Third item |
| 55 | + |
| 56 | +Another list: |
| 57 | + |
| 58 | +1. First step |
| 59 | +1. Second step |
| 60 | +1. Third step |
| 61 | +``` |
| 62 | + |
| 63 | +**Bad:** |
| 64 | + |
| 65 | +```markdown |
| 66 | +No blank line before list: |
| 67 | +- Item one |
| 68 | + |
| 69 | +- Blank lines between items |
| 70 | +- Not needed |
| 71 | + |
| 72 | +* Wrong marker |
| 73 | ++ Mixed markers |
| 74 | +``` |
| 75 | + |
| 76 | +## Code Blocks |
| 77 | + |
| 78 | +- Always use fenced code blocks (triple backticks) with language identifiers |
| 79 | +- Always include a blank line before and after code blocks |
| 80 | +- Specify the language for syntax highlighting (`bash`, `python`, `markdown`, `json`, etc.) |
| 81 | +- Use `plaintext` or `text` if no specific language applies |
| 82 | +- Indent code blocks at the same level as surrounding content |
| 83 | + |
| 84 | +**Good:** |
| 85 | + |
| 86 | +```markdown |
| 87 | +Here is an example: |
| 88 | + |
| 89 | +\`\`\`bash |
| 90 | +echo "Hello, world!" |
| 91 | +\`\`\` |
| 92 | + |
| 93 | +The command prints a message. |
| 94 | +``` |
| 95 | + |
| 96 | +**Bad:** |
| 97 | + |
| 98 | +```markdown |
| 99 | +No language identifier: |
| 100 | +\`\`\` |
| 101 | +code here |
| 102 | +\`\`\` |
| 103 | +No blank lines before/after code blocks. |
| 104 | +``` |
| 105 | + |
| 106 | +## Links |
| 107 | + |
| 108 | +- Use reference-style links for repeated URLs |
| 109 | +- Use relative paths for internal links (relative to the current file) |
| 110 | +- Always provide link text in square brackets: `[text](url)` |
| 111 | +- Do not use bare URLs (wrap them: `<https://example.com>`) |
| 112 | +- For internal repository links, use relative paths starting with `./` or `../` |
| 113 | +- Use `.md` extension for links to Markdown files |
| 114 | + |
| 115 | +**Good:** |
| 116 | + |
| 117 | +```markdown |
| 118 | +See the [installation guide](../docs/installation.md) for details. |
| 119 | + |
| 120 | +Check out [GitHub][gh] and [GitLab][gl] for hosting. |
| 121 | + |
| 122 | +[gh]: https://github.com |
| 123 | +[gl]: https://gitlab.com |
| 124 | +``` |
| 125 | + |
| 126 | +**Bad:** |
| 127 | + |
| 128 | +```markdown |
| 129 | +Absolute path: [guide](/docs/installation.md) |
| 130 | +Missing extension: [guide](../docs/installation) |
| 131 | +Bare URL: Visit https://example.com |
| 132 | +``` |
| 133 | + |
| 134 | +## Tables |
| 135 | + |
| 136 | +- Use tables when content follows a consistent structure (instead of lists) |
| 137 | +- Align columns using hyphens for readability |
| 138 | +- Include header row separator with at least 3 hyphens per column |
| 139 | +- Surround tables with blank lines (one before, one after) |
| 140 | +- Use pipes (`|`) to separate columns |
| 141 | +- Align content within columns for readability (optional but recommended) |
| 142 | + |
| 143 | +**Good:** |
| 144 | + |
| 145 | +```markdown |
| 146 | +Here is a comparison: |
| 147 | + |
| 148 | +| Feature | Supported | Notes | |
| 149 | +|---------|-----------|-------| |
| 150 | +| Feature A | Yes | Fully supported | |
| 151 | +| Feature B | No | Planned for v2 | |
| 152 | +| Feature C | Partial | Beta feature | |
| 153 | + |
| 154 | +The table shows current status. |
| 155 | +``` |
| 156 | + |
| 157 | +**Bad:** |
| 158 | + |
| 159 | +```markdown |
| 160 | +Using list when table is better: |
| 161 | +- Feature A: Yes - Fully supported |
| 162 | +- Feature B: No - Planned for v2 |
| 163 | +- Feature C: Partial - Beta feature |
| 164 | +``` |
| 165 | + |
| 166 | +## Requirement Number Formatting |
| 167 | + |
| 168 | +When writing or referencing requirement numbers (NFR and FR) in documentation: |
| 169 | +- **Always use bold formatting** for requirement numbers |
| 170 | +- **Replace hyphens with non-breaking hyphens** (`‑`) between letters and numbers |
| 171 | +- This prevents line breaks within requirement numbers and ensures consistent formatting |
| 172 | +- This applies to all specification documents, plans, and tables |
| 173 | + |
| 174 | +Examples: |
| 175 | +```markdown |
| 176 | +# Correct formatting |
| 177 | +**NFR‑001**: The system must respond within 200ms |
| 178 | +**FR‑042**: User authentication shall support OAuth 2.0 |
| 179 | + |
| 180 | +# In tables |
| 181 | +| ID | Description | |
| 182 | +|----|-------------| |
| 183 | +| **NFR‑001** | Performance requirement | |
| 184 | +| **FR‑042** | Authentication feature | |
| 185 | + |
| 186 | +# Incorrect formatting (do not use) |
| 187 | +NFR-001: Without bold or non-breaking hyphen |
| 188 | +**NFR-001**: Bold but with regular hyphen (can break across lines) |
| 189 | +NFR‑001: Non-breaking hyphen but not bold |
| 190 | +``` |
| 191 | + |
| 192 | +## Emphasis |
| 193 | + |
| 194 | +- Use `*` or `_` for emphasis (italic), `**` or `__` for strong emphasis (bold) |
| 195 | +- Be consistent within a document (prefer `*` and `**`) |
| 196 | +- Do not use emphasis for headings |
| 197 | +- Use backticks for code/technical terms, not emphasis |
| 198 | + |
| 199 | +**Good:** |
| 200 | + |
| 201 | +```markdown |
| 202 | +This is *emphasized* text. |
| 203 | +This is **strong** text. |
| 204 | +Use the `--verbose` flag for details. |
| 205 | +``` |
| 206 | + |
| 207 | +**Bad:** |
| 208 | + |
| 209 | +```markdown |
| 210 | +This is _emphasized_ text with **strong** mixed styles. |
| 211 | +Use the *--verbose* flag (should be backticks). |
| 212 | +``` |
| 213 | + |
| 214 | +## Line Length |
| 215 | + |
| 216 | +- Wrap prose at 80-120 characters per line |
| 217 | +- Do not wrap code blocks, tables, or URLs |
| 218 | +- Break after sentences or at natural phrase boundaries |
| 219 | +- Empty lines do not count toward line length |
| 220 | + |
| 221 | +## Whitespace |
| 222 | + |
| 223 | +- Use a single blank line to separate blocks of content |
| 224 | +- Do not use multiple consecutive blank lines |
| 225 | +- End files with a single newline character |
| 226 | +- Do not use trailing whitespace at the end of lines |
| 227 | +- Use spaces (not tabs) for indentation |
| 228 | + |
| 229 | +## Other Rules |
| 230 | + |
| 231 | +### Horizontal Rules |
| 232 | + |
| 233 | +- Use three hyphens (`---`) for horizontal rules |
| 234 | +- Surround horizontal rules with blank lines |
| 235 | + |
| 236 | +**Good:** |
| 237 | + |
| 238 | +```markdown |
| 239 | +Section one content. |
| 240 | + |
| 241 | +--- |
| 242 | + |
| 243 | +Section two content. |
| 244 | +``` |
| 245 | + |
| 246 | +### Blockquotes |
| 247 | + |
| 248 | +- Use `>` for blockquotes with a space after |
| 249 | +- Surround blockquotes with blank lines |
| 250 | +- Use multiple `>` for nested quotes |
| 251 | + |
| 252 | +**Good:** |
| 253 | + |
| 254 | +```markdown |
| 255 | +As the docs state: |
| 256 | + |
| 257 | +> This is an important note. |
| 258 | +> It spans multiple lines. |
| 259 | + |
| 260 | +Back to regular text. |
| 261 | +``` |
| 262 | + |
| 263 | +### Images |
| 264 | + |
| 265 | +- Use alt text for all images: `` |
| 266 | +- Use relative paths for repository images |
| 267 | +- Prefer reference-style for repeated images |
| 268 | + |
| 269 | +**Good:** |
| 270 | + |
| 271 | +```markdown |
| 272 | + |
| 273 | + |
| 274 | +See the [logo][logo-img] above. |
| 275 | + |
| 276 | +[logo-img]: ./images/logo.png |
| 277 | +``` |
| 278 | + |
| 279 | +### HTML |
| 280 | + |
| 281 | +- Avoid HTML in Markdown when possible |
| 282 | +- Use HTML only for features not supported by Markdown |
| 283 | +- Close all HTML tags properly |
| 284 | + |
| 285 | +### Filenames |
| 286 | + |
| 287 | +- Use lowercase for Markdown filenames |
| 288 | +- Use hyphens (`-`) not underscores (`_`) to separate words |
| 289 | +- Use `.md` extension (not `.markdown`) |
| 290 | + |
| 291 | +**Examples:** |
| 292 | + |
| 293 | +- `installation-guide.md` ✅ |
| 294 | +- `Installation_Guide.markdown` ❌ |
| 295 | + |
| 296 | +## Linting |
| 297 | + |
| 298 | +To validate Markdown files against these guidelines, use a Markdown linter such as: |
| 299 | + |
| 300 | +- [markdownlint](https://github.com/DavidAnson/markdownlint) |
| 301 | +- [remark-lint](https://github.com/remarkjs/remark-lint) |
| 302 | +- [superlinter](https://github.com/super-linter/super-linter) |
| 303 | + |
| 304 | +Configure the linter to enforce these rules in your CI/CD pipeline. |
0 commit comments