Markdown Basics for Documentation — Complete Guide
In this tutorial, you will learn about Markdown Basics for Documentation. We cover key concepts, practical examples, and best practices to help you master this topic.
Markdown is a lightweight markup language for formatting plain text. Learn headings, lists, code blocks, tables, links, images, and extended syntax used across all documentation platforms.
What You'll Learn
You will learn Markdown syntax from basics to advanced extensions, how to structure documentation files, and how to use Markdown with static site generators for rich documentation.
Why It Matters
Markdown is the standard format for docs-as-code. Every static site generator, code hosting platform, and documentation tool supports it. Mastering Markdown means you can write documentation anywhere without learning new tools.
Real-World Use
The DodaTech tutorials platform uses Markdown for every page. Hugo converts Markdown to HTML with syntax highlighting, tables, and shortcodes for interactive elements.
flowchart LR A[Markdown File] --> B[Static Site Generator] B --> C[HTML Page] C --> D[Responsive Website] A:::current classDef current fill:#f90,color:#fff,stroke:#333,stroke-width:2px
Basic Markdown Syntax
Headings
# Heading 1 (Page Title)
## Heading 2 (Section)
### Heading 3 (Subsection)
#### Heading 4 (Sub-subsection)
Use exactly one H1 per page for the title. Use H2 for main sections and H3 for subsections.
Text Formatting
**Bold text** for emphasis
*Italic text* for technical terms
`Inline code` for commands and variable names
~~Strikethrough~~ for deprecated content
Lists
1. First step
2. Second step
3. Third step
- Unordered item
- Another item
- Nested item (indent with two spaces)
Links
[Link text](https://example.com)
[Relative link](/docs/getting-started/)
[Reference-style link][ref-id]
[ref-id]: https://example.com
Images
Code Blocks
Fenced Code Blocks
```python
def hello():
print("Hello, world!")
### Inline Code
Use backticks for inline code: `npm install`.
### Syntax Highlighting
```markdown
```<a href="/programming-languages/javascript/">JavaScript</a>
const greeting = "Hello, world!";
console.log(greeting);
**Expected output**: Syntax-highlighted code blocks with line numbers and a copy button (enabled by Hugo).
## Tables
```markdown
| Tool | Language | Build Speed |
|------|----------|-------------|
| Hugo | Go | <1s for 10K pages |
| Docusaurus | React | 2-5s for 1K pages |
| MkDocs | Python | 1-3s for 1K pages |
| Tool | Language | Build Speed |
|---|---|---|
| Hugo | Go | <1s for 10K pages |
| Docusaurus | React | 2-5s for 1K pages |
| MkDocs | Python | 1-3s for 1K pages |
Extended Markdown Syntax
Many static site generators support extensions beyond basic Markdown:
Footnotes
This is a statement with a footnote.[^1]
[^1]: The footnote content appears at the bottom of the page.
Task Lists
- [x] Write the installation guide
- [ ] Add troubleshooting section
- [ ] Review by technical writer
Definition Lists
API
: Application Programming Interface — a set of rules for interacting with a service.
SDK
: Software Development Kit — a collection of tools and libraries for building applications.
Organizing Documentation in Markdown
---
title: "Installation Guide"
weight: 10
---
# Installation Guide
Welcome to the installation guide. By the end of this guide,
you will have the software running on your local machine.
## Prerequisites
Before starting, ensure you have:
- Node.js 18 or later
- npm 9 or later
- A code editor
## Installation Steps
1. Download the latest release from GitHub.
2. Extract the archive to your preferred location.
3. Run `npm install` to install dependencies.
4. Run `npm start` to launch the application.
Common Mistakes
1. Using Too Many Heading Levels
Stick to H1, H2, and H3. H4 and beyond create visual clutter and make navigation harder.
2. Forgetting Blank Lines
Markdown requires blank lines between block elements. A heading immediately after a paragraph without a blank line may not render correctly.
3. Inconsistent List Formatting
Mix ordered and unordered lists inconsistently. Use one space after the list marker consistently.
4. Broken Image Paths
Images referenced with relative paths break when files move. Use absolute paths in the static folder or verify paths in CI.
5. Overusing HTML in Markdown
While Markdown supports inline HTML, mixing formats creates maintenance problems. Use native Markdown syntax when possible.
6. Neglecting Alt Text
Images without alt text fail Accessibility checks. Every image must have a descriptive alt attribute.
7. Writing Long Lines
Markdown renders paragraphs regardless of line breaks, but long lines are hard to diff in Git. Use one sentence per line for better diffs.
Practice Questions
1. How do you create a level-2 heading in Markdown?
Use two hash symbols: ## Heading Name
2. What is the syntax for a fenced code block with syntax highlighting?
Triple backticks followed by the language name: ```python
3. How do you create a link to another page in the same documentation site?
Use a relative path: [Getting Started](/getting-started/)
4. Why should images have alt text?
Alt text provides descriptions for screen readers and displays when images fail to load. It is required for WCAG Compliance.
5. Challenge: Write a Markdown page that includes a table comparing three tools, a code block with syntax highlighting, an ordered list of steps, and an image with alt text.
FAQ
Mini Project
Create a Markdown documentation page for a simple API endpoint. Include a title, description, authentication notes, a request example in curl, a response example in JSON, a parameter table, error codes, and a code example in two languages.
What's Next
Now that you know Markdown, learn about Static Site Generators that convert your Markdown files into a full documentation website. Then explore the Documentation Build Pipeline.
Built by the developers of DodaTech
Doda Browser, DodaZIP & Durga Antivirus Pro