A clean, complete guide for anyone writing better README files.
Markdown is a lightweight markup language that lets you format text using simple symbols. It’s widely used in GitHub READMEs, documentation, wikis, blogs, and notes.
Headings help structure your README into clear, readable sections. Simply it makes the document easy to scan.
# This is a Heading## This is a Heading### This is a Heading
Formatting helps you highlight important info, emphasize details, or organize explanations. It makes your README clearer, more readable, and more professional.
Bold Text
**Bold Text** or __Bold Text__Italic Text
*Italic Text* or _Italic Text_Bold + Italic
***Bold + Italic***Strikethrough
`~~Strikethrough~~` or `~Strikethrough~`Underline
<ins>Underline<ins>Here's is a subscript
<sub>subscript<sub>Here's is a superscript
<sup>superscript<sup>inline code
`inline code`Lists help you present information cleanly and quickly, making complex steps or features easy to digest.
- Item 1
- Item 2
- Item 1 - Item 2
- Item 1
- Item 2
1. Item 1 2. Item 2
- Item 1
- Sub Item 1
- Sub item a
- Item 1 - Sub Item 1 - Sub item a
- Completed task
- Pending task
- [x] Completed task - [ ] Pending task
Code blocks make your README developer‑friendly, giving users clean, formatted examples they can copy and run.
Use npm install to install packages.
`npm install`
print("Hello World")```python
print("Hello World")
```
Syntax highlighting available for Python, JavaScript, Java, Bash, JSON, YAML etc.
```<syntax>
<code>
```
GitHub supports Mermaid for diagrams. Very useful for architecture diagrams, flowcharts, and explaining project structure: essential for technical documentation.
flowchart TD
A --> B
Syntax:
```mermaid
flowchart TD
A --> B
```
Tables allow you to show structured information such as configurations, comparisons, or fields. It turns messy text into a clean, organized layout, especially useful for feature lists, API data, and documentation.
| Name | Role | Level |
|---|---|---|
| John | Developer | Senior |
| Bob | Tester | Junior |
| Name | Role | Level |
|--------|-----------|--------|
| John | Developer | Senior |
| Bob | Tester | Junior |or
|Name|Role|Level|
|-|-|-|
|John|Developer|Senior|
|Bob|Tester|Junior|Used for notes, warnings, tips, or important messages.
This is a quoted line.
Nested quote
> This is a quoted line.
>> Nested quote---Links lets us connect users to installation guides, docs, external pages, or related repositories.
Syntax:
[GitHub](https://github.com)
Images help make your README visually appealing, making your README more engaging and easier to understand.
Syntax:


Alerts are use to emphasize critical information. On GitHub, they are displayed with distinctive colors and icons to indicate the significance of the content.
Note
Useful information that users should know, even when skimming content.
> [!NOTE]
> Useful information that users should know, even when skimming content.
Tip
Helpful advice for doing things better or more easily.
> [!TIP]
> Helpful advice for doing things better or more easily.
Important
Key information users need to know to achieve their goal.
> [!IMPORTANT]
> Key information users need to know to achieve their goal.
Warning
Urgent info that needs immediate user attention to avoid problems.
> [!WARNING]
> Urgent info that needs immediate user attention to avoid problems.
Caution
Advises about risks or negative outcomes of certain actions.
> [!CAUTION]
> Advises about risks or negative outcomes of certain actions.
