Intermediate

Markdown Best Practices

Write clean, maintainable Markdown with these best practices for file organization, accessibility, collaboration, and a complete syntax cheat sheet.

Writing Clean Markdown

One sentence per line
In source files, start each sentence on a new line. This makes diffs cleaner in version control. The rendered output will be the same since Markdown treats single line breaks as spaces.
Consistent heading hierarchy
Use only one H1 per document. Do not skip levels (do not go from H2 to H4). Use headings to create a logical document outline.
Blank lines around block elements
Add blank lines before and after headings, code blocks, lists, and blockquotes. This ensures consistent rendering across all Markdown parsers.
Use reference-style links for readability
When a document has many links, use reference-style links at the bottom to keep the text readable.
Consistent list markers
Pick one style for unordered lists (-, *, or +) and stick with it throughout the document. Most style guides recommend hyphens (-).

File Organization

Documentation Structure

docs/
  README.md              # Overview and navigation
  getting-started.md     # Setup and installation
  configuration.md       # Configuration options
  guides/
    authentication.md    # Auth guide
    deployment.md        # Deployment guide
  api/
    endpoints.md         # API reference
    errors.md            # Error codes
  images/
    architecture.png     # Diagrams and screenshots
    logo.svg

Naming Conventions

File names: Use lowercase with hyphens: getting-started.md, not Getting Started.md
Directories: Use lowercase with hyphens: api-reference/, not API Reference/
Images: Descriptive names: login-flow-diagram.png, not image1.png
Special files: UPPERCASE for standard files: README.md, CHANGELOG.md, CONTRIBUTING.md

Accessibility in Markdown

Making your Markdown accessible ensures everyone can consume your content:

Alt Text for Images

Always provide descriptive alt text: ![Chart showing 40% growth in Q3](chart.png) not ![](chart.png)

Descriptive Link Text

Use [read the API docs](url) not [click here](url). Screen readers announce link text out of context.

Heading Structure

Use proper heading hierarchy for screen reader navigation. Do not use headings just for visual styling.

Language Specification

Always specify the language in fenced code blocks. Screen readers and syntax highlighters use this information.

Common Mistakes

Mistake	Problem	Fix
No space after #	`#Heading` may not render	Always: `# Heading`
No blank line before list	List may not render properly	Add blank line before first list item
Skipping heading levels	Breaks document outline	Go H1 > H2 > H3, never skip
Inconsistent list markers	Mixing -, *, + looks messy	Pick one style and stick with it
Missing alt text	Images inaccessible to screen readers	Always add descriptive alt text
Using HTML unnecessarily	Reduces portability and readability	Use Markdown syntax when possible
Very long lines	Hard to read in source, bad diffs	Break at sentence boundaries

Version Control for Docs

Track documentation alongside code: Keep docs in the same repository as the code they document.
Review doc changes in PRs: Documentation changes should go through the same review process as code changes.
One sentence per line: This produces cleaner git diffs when editing text.
Use .markdownlint.json: Enforce consistent style across contributors with automated linting.
Automate checks: Add markdown linting to CI/CD pipeline to catch issues before merge.

Markdown Cheat Sheet

Element	Syntax	Notes
Heading 1-6	`# to ######`	Space after # required
Bold	`text`	Or `__text__`
Italic	`text`	Or `_text_`
Bold + Italic	`*text*`
Strikethrough	`~~text~~`	GFM extension
Link	`[text](url)`	Add "title" for hover text
Image	`![alt](url)`	Always include alt text
Unordered List	`- item`	Or * or +
Ordered List	`1. item`	Numbers auto-increment
Task List	`- [x] done`	GFM extension
Blockquote	`> text`	Nest with >>
Inline Code	`code`
Code Block	```lang```	Specify language for highlighting
Horizontal Rule	`---`	Or *** or ___
Table	`\| col \| col \|`	Use :-- --: for alignment
Footnote	`[^1]`	Define at bottom of doc
Emoji	`:emoji_name:`	Platform-dependent
Math	$equation$	LaTeX syntax
Escape	`\*`	Backslash before special chars

Frequently Asked Questions

Should I use Markdown or a WYSIWYG editor?

For technical content, documentation, and anything that lives in a Git repository, Markdown is strongly preferred. It plays well with version control, is portable across tools, and is readable without rendering. Use WYSIWYG editors (Google Docs, Word) for content that needs complex formatting like brochures, presentations, or documents shared with non-technical stakeholders.

How do I add images to a Markdown document?

Use the syntax ![alt text](path/to/image.png). For GitHub, you can drag and drop images directly into the editor. For local files, store images in an images/ or assets/ directory relative to your Markdown file and use relative paths. For web images, use the full URL.

Can I use HTML inside Markdown?

Yes, most Markdown parsers allow inline HTML. This is useful for elements Markdown does not support natively (like centered text, colored text, or collapsible sections). However, overusing HTML reduces readability and portability. Use it sparingly and only when Markdown cannot achieve what you need.

What is the difference between .md and .markdown?

They are the same thing. Both extensions indicate a Markdown file. The .md extension is far more common and is the standard used by GitHub, GitLab, and most tools. Use .md unless you have a specific reason to use .markdown.

How do I create a table of contents automatically?

Several approaches: (1) VS Code's "Markdown All in One" extension can generate a TOC with a command. (2) Tools like doctoc generate TOCs as part of a build process. (3) GitHub automatically creates a TOC button on rendered Markdown files with multiple headings. (4) Some static site generators (MkDocs, Docusaurus) create navigation automatically from headings.

📚

Congratulations! You have completed the Markdown course. You now have the skills to write professional documentation, structure AI prompts effectively, and use Markdown across all the platforms where it is supported. Continue exploring with the Prompt Engineering or Context Engineering courses.