Markdown is designed to be readable as plain text and renderable as formatted HTML. When you write it well, it works correctly on GitHub, in documentation tools, in static site generators, and in editors. When you write it carelessly, you get inconsistent rendering across platforms.
These practices apply to any markdown file, whether you're writing a README, a blog post, or technical documentation.
Use headers in sequence
Headers should go in order: h1, then h2, then h3. Skipping levels for visual reasons breaks the document outline and causes accessibility problems.
# Document Title
## First Section
### Subsection
## Second Section
Don't use h3 because you want smaller text. Use CSS for that. The heading hierarchy is semantic, not visual.
Most documents should have exactly one h1. On GitHub, the repo name already acts as a title, so many READMEs start with h2.
Write alt text for every image
Alt text is read by screen readers and displayed when images fail to load. It also gives search engines context about image content.
Bad alt text:  or .
Good alt text describes what's in the image and why it's there. For decorative images that add no information, use an empty alt attribute: .
Always specify language in code blocks
Fenced code blocks without a language identifier don't get syntax highlighting. Specify it every time.
```javascript
function formatDate(date) {
return date.toISOString().split('T')[0];
}
```
Common language identifiers: javascript, typescript, python, bash, sql, json, yaml, html, css, markdown. For shell commands, use bash or sh.
Consistent list formatting
Pick one style for unordered lists (-, *, or +) and use it throughout the document. Mixing them works in most renderers but looks inconsistent in raw text.
For ordered lists, use 1. for every item rather than incrementing manually. Markdown renderers handle the numbering. This makes it much easier to reorder items.
1. First item
1. Second item
1. Third item
This renders as 1, 2, 3 correctly.
Line length and blank lines
Keep lines under 100 characters where possible. Longer lines are harder to review in diffs and in terminals.
Always use blank lines between block elements: before and after headings, before and after code blocks, before and after lists. Some renderers require this; all renderers benefit from it.
## Section heading
Some paragraph text here.
- List item one
- List item two
Another paragraph.
Link text should be descriptive
Avoid "click here" or "read more" as link text. Screen readers often read links out of context, so the link text needs to make sense on its own.
<!-- Avoid -->
For more information, [click here](/docs).
<!-- Better -->
See the [md0 documentation](/docs) for details.
Use reference-style links for long URLs
When a URL is long, inline links make the raw markdown hard to read. Reference-style links keep the text clean.
The [live editor][live-editor] and [table generator][table-gen] are the most used tools.
[live-editor]: https://md0.io/live-editor
[table-gen]: https://md0.io/to-table
Avoid inline HTML where possible
Most markdown processors support inline HTML, but mixing HTML into markdown creates documents that are harder to read in raw form and may not render correctly in all contexts.
Exceptions: tables with complex alignment requirements, <details> and <summary> for collapsible sections on GitHub, and <sub>/<sup> for subscripts.
Validate your output
Paste your markdown into different renderers occasionally. GitHub, GitLab, and VS Code all render markdown, and they handle edge cases slightly differently. What looks fine in one may break in another.
md0's live editor gives you real-time preview as you type, which catches most formatting problems immediately. The markdown formatter can clean up inconsistent spacing and list styles automatically.
Frontmatter
If your markdown will be processed by a static site generator or CMS, add YAML frontmatter for metadata. Keep it minimal: only fields the build system actually uses.
---
title: "Document Title"
date: "2025-01-15"
---
# Content starts here
These rules aren't exhaustive, but following them consistently means your markdown will behave predictably regardless of where it ends up. Start with the live editor to write your next document and see formatting issues caught in real-time.