Write better Markdown with small habits
Markdown's strength is its simplicity, but simple does not mean there is nothing to learn. A few consistent habits separate Markdown that is clean and maintainable from Markdown that becomes a mess the moment someone else tries to edit it. These ten tips cover the elements you will use every day — headings, emphasis, links, lists, code blocks, tables, and more — with practical examples for each.
1. Use headings to create document structure
Headings do two things: they create visual hierarchy for readers, and they signal document structure to renderers, search engines, and accessibility tools. Use a single # H1 per document for the title, then ## H2 for major sections, and ### H3 for subsections within those sections.
Skipping levels — jumping from H1 directly to H3 — creates broken structure that screen readers and document outlines handle poorly. Keep the hierarchy consistent.
# Document Title (H1 — one per page) ## Major Section (H2) ### Subsection (H3) #### Detail (H4 — use sparingly)
2. Format emphasis with purpose
Markdown offers two levels of emphasis: *italic* for mild emphasis or titles, and **bold** for strong emphasis on key terms or warnings. Both styles render identically whether you use asterisks or underscores, but pick one convention and stick to it throughout a document — mixing them adds unnecessary visual noise in the source.
Reserve bold for content that genuinely needs to stand out. A document where every other phrase is bold trains readers to ignore the formatting entirely.
Use _italic_ for titles, terms, or gentle emphasis. Use **bold** for critical information or key terms. Use ~~strikethrough~~ to indicate removed or deprecated content.
3. Write descriptive link text
Link text is a signal to both readers and search engines about what the destination page contains. "Click here" or "read more" tells neither a human nor a crawler anything useful. Descriptive link text — the phrase that describes the destination — is more accessible, more scannable, and better for SEO.
Avoid: [click here](https://markdown.co.in/markdown-guide.html) Prefer: [complete Markdown syntax guide](https://markdown.co.in/markdown-guide.html) Avoid: [read more](https://markdown.co.in/markdown-cheat-sheet.html) Prefer: [Markdown cheat sheet with examples](https://markdown.co.in/markdown-cheat-sheet.html)
4. Keep lists consistent
Markdown supports unordered lists with -, *, or + as the bullet character, and ordered lists with 1. numbers. Within a single list, use only one bullet style. Switching mid-list can cause parsers to treat items as separate lists, and it makes source files harder to scan.
For ordered lists, you can number every item 1. and let the renderer increment automatically — this makes reordering items easier without having to renumber manually.
- First item - Second item - Third item 1. First step 1. Second step 1. Third step (renderer outputs 1, 2, 3 automatically)
5. Use task lists for actionable content
GitHub Flavored Markdown supports task lists — checkboxes that render as interactive elements on GitHub and in most Markdown editors. They are useful for sprint to-dos, release checklists, onboarding documents, and any list where completion state matters.
- [x] Write the first draft - [x] Review and edit - [ ] Add code examples - [ ] Final proofread - [ ] Publish
Task lists committed to a repository give teams a lightweight project tracker that lives next to the code, requires no external tool, and shows up in pull request diffs like any other content change.
6. Annotate code blocks with a language identifier
Fenced code blocks with a language identifier enable syntax highlighting in GitHub, documentation sites, and most Markdown editors. The identifier immediately follows the opening three backticks with no space.
```python
def greet(name: str) -> str:
return f"Hello, {name}"
```
```javascript
function greet(name) {
return `Hello, ${name}`;
}
```
```bash
echo "Hello, world"
```
Always include the language identifier. A code block without one renders as plain text — readers lose the syntax colouring that makes code easier to scan, and tools that auto-generate documentation cannot detect the language.
7. Build tables for structured comparisons
GFM table syntax uses pipes to separate columns and hyphens to create the header separator row. The column separator row also controls alignment: default is left, :---: centres, and ---: right-aligns.
| Feature | Free Plan | Pro Plan | |----------------|:---------:|:--------:| | Live preview | Yes | Yes | | Export to PDF | No | Yes | | Custom themes | No | Yes | | Storage | Local | Cloud |
Keep table column widths consistent in the source even though the renderer ignores extra spaces. A well-formatted source table is much easier to edit than one where every row has different padding.
8. Always include alt text on images
The alt attribute in Markdown image syntax is not optional — it serves both accessibility and SEO. Screen readers announce the alt text to users who cannot see the image. Search engine crawlers use it to understand image content. An empty alt  is worse than no image at all for accessibility.
Avoid:  Prefer: 
Write alt text that describes what the image shows, not what you want it to mean. "Screenshot of editor" is useful. "Click to try our amazing editor" is not alt text — it is an advertisement.
9. Use blockquotes for callouts and attribution
Blockquotes are created with a leading > character. They work well for callout notes, important warnings, and attributed quotations. In many documentation themes, they render as visually distinct highlighted boxes.
> Note: This feature requires Node.js 18 or later. > The goal of Markdown is not to replace HTML; it's to make writing for the web > as easy as writing plain email. > — John Gruber, 2004
Some documentation platforms (Docusaurus, GitBook, MkDocs with admonition plugins) extend blockquote syntax with typed callouts like > [!WARNING] or > [!NOTE] that render with coloured icons. Check your renderer's documentation for available extensions.
10. Keep it simple — Markdown's best feature is restraint
Markdown's intentional limitations are a feature. It does not support arbitrary colours, font sizes, or complex layouts because most prose writing does not need them. When you find yourself reaching for inline HTML to achieve a formatting effect, ask whether the content actually needs that formatting or whether the writing itself needs to be clearer.
Heavily formatted Markdown — with inline HTML, custom styles, and complex nested structures — defeats the purpose of the format. It becomes harder to read in source form, harder to version-control meaningfully, and harder for contributors to edit. Write in Markdown the way you would write a well-structured email: clearly, with structure where structure helps, and plainly everywhere else.
Practice these tips in the editor
Try every example from this guide in the live editor — real-time preview, syntax highlighting, and export included.