Markdown Documentation
Markdown is a lightweight markup language that formats plain text using simple, readable symbols. GitHub automatically renders Markdown files with headings, lists, links, tables, and code blocks.
Markdown files commonly use the .md
extension. The most important example in many
repositories is README.md, which
introduces the project and explains how to use it.
1. Headings
Use the hash symbol (#) followed by a
space to create headings. The number of hashes
determines the heading level.
# Document Title
## Major Section
### Subsection
#### Smaller Heading
##### Level Five Heading
###### Level Six Heading
Rendered Example
Document Title
Major Section
Subsection
2. Text Formatting
Use Markdown symbols to emphasize important text.
*Italic text*
**Bold text**
***Bold and italic text***
~~Strikethrough text~~
Rendered Example
Italic text
Bold text
Bold and italic text
Strikethrough text
3. Lists
Use hyphens or asterisks for bullet lists and numbers for ordered lists.
- First item
- Second item
- Nested item
1. First step
2. Second step
3. Third step
Rendered Example
- First item
-
Second item
- Nested item
- First step
- Second step
- Third step
4. Links and Images
Links use square brackets for the display text and parentheses for the destination URL. Images use the same syntax with an exclamation mark at the beginning.
[GitHub](https://github.com)

Rendered Example
An image will appear when the specified image path exists in the repository.
./images/architecture.png are useful when
the image is stored inside your repository.
5. Inline Code and Code Blocks
Use single backticks for commands inside a sentence. Use triple backticks for multi-line code examples. Adding a language identifier enables syntax highlighting on supported Markdown platforms.
Use `git status` to check repository changes.
Example of a fenced Bash code block:
```bash
git checkout -b feature/login
git add .
git commit -m "Add login feature"
```
On GitHub, the fenced example is rendered as a formatted code block rather than ordinary paragraph text.
6. Tables
Tables help present commands, descriptions, and other structured information.
| Command | Purpose |
| --- | --- |
| `git pull` | Fetches and integrates remote changes |
| `git push` | Uploads local commits to a remote repository |
| `git status` | Shows the working tree status |
Rendered Example
| Command | Purpose |
|---|---|
git pull |
Fetches and integrates remote changes |
git push |
Uploads local commits to a remote repository |
git status |
Shows the working tree status |
7. Task Lists
GitHub supports task lists that are useful for tracking project setup steps and documentation work.
- [x] Create project repository
- [ ] Configure GitHub Actions
- [ ] Deploy production files
Rendered Example
Create project repository
Configure GitHub Actions
Deploy production files
8. Writing a Good README.md
A useful README helps developers understand your project before they start using or contributing to it.
# Project Name
## Overview
Describe what your project does.
## Features
- Feature one
- Feature two
## Requirements
List the required software and dependencies.
## Installation
Explain how to clone and configure the project.
## Usage
Show how to run and use the application.
## Contributing
Explain how others can contribute.
A README commonly includes:
- Project name and purpose
- Features and screenshots
- Prerequisites and installation steps
- Usage instructions and examples
- Contribution guidelines and license information
9. Markdown Best Practices
- Use headings to divide long documents into clear sections.
- Keep paragraphs short and easy to scan.
- Format terminal commands using inline code or fenced code blocks.
- Use meaningful link text and image alternative text.
- Include installation and usage instructions in your README.
- Preview the rendered Markdown before publishing changes.