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|We can also align text to the left, right, or center of a column by including colons ':' to the left, right, or on both sides of the hyphens within the header row.
| Left Aligned | Centered | Right Aligned |
|---|---|---|
| name1 | role1 | level1 |
| name2 | role2 | level2 |
|Left Aligned| Centered |Right Aligned|
|:--- | :---: | ---:|
| name1 | role1 | level1|
| name2 | role2 | level2|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:
?target=https://github.com
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.
Markdown is powerful, but it has limits. GitHub supports HTML inside Markdown, letting you do layout tricks that plain Markdown cannot achieve. Below is the full detailed explanation of how HTML can enhance Markdown.
Markdown headings are good, but HTML headings gives more control. Useful when you want alignment or mixed layout at the top.
<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3><h2 align="left">Left Aligned</h1>
<h2 align="center">Centered</h2>
<h2 align="right">Right Aligned</h3>Markdown sometimes collapses line breaks. HTML fixes that.
This is a paragraph with controlled spacing.
<p>This is a paragraph with controlled spacing.</p>Line 1
Line 2
Line 1 <br>
Line 2Comments are notes that won't render on the markdown, useful in add info without showing them publicly.
<!-- This is a Comment -->
<!--
This is
also a
Comment
-->We can tweak the alignment of elements using the 'align' attribute on some tags. It is very useful to get a clean professional look for README's top section.
<div align="center"> <img src="assets/logo.png" alt="Logo" width="120" /> <h1>Project Name</h1> <p>A short one‑line description of what your project does.</p> </div>
Using <a> tag we can add links inside centered blocks, badge rows, or custom layouts where Markdown links get messy.
<a href="https://example.com" title="Example">Example Site</a>Markdown lists are usually enough, but HTML lists help when you’re mixing complex blocks or alignment. We use <ul> <li> for unordered lists, <ol> <li> for ordered lists.
- list 1
- list 2
<ul>
<li>list 1</li>
<li>list 2</li>
</ul>- list 1
- list 2
<ol>
<li>list 1</li>
<li>list 2</li>
</ol>HTML tables are more flexible than Markdown tables. These are great for side‑by‑side layouts and for content that breaks Markdown table formatting.
| Column 1 | Column 2 |
| Data | Data |
| Data | Data |
<table align='center'>
<tr>
<td>Column 1</td>
<td>Column 2</td>
</tr>
<tr>
<td>Data</td>
<td>Data</td>
</tr>
<tr>
<td>Data</td>
<td>Data</td>
</tr>
</table>Within our README we can use <details> and summary> tag to create expandable sections. These collapsible sections are perfect for FAQ, advanced setup, more screenshots, or extended configuration without making the README huge.
Show advanced setup
- Step 1: Do this
- Step 2: Do that
<details>
<summary>Show advanced setup</summary>
- Step 1: Do this
- Step 2: Do that
</details>Anchors helps navigation in long READMEs. GitHub supports TOC linking behavior as part of common README practice.
[Section1](#section1)
[Section2](#section2)We can use <kbd> to display keyboard keys nicely. It is useful for shortcuts or commands in guides.
Press Ctrl + C to Copy.
Press Ctrl + V to Paste.Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to Copy. Press <kbd>Ctrl</kbd> + <kbd>V</kbd> to Paste.
Tip
- Start with a 1–2 line summary explaining what the project does and who it’s for.
- Add a clear title + short tagline (people decide in 5 seconds).
- Show a screenshot/GIF early (especially for UI tools, dashboards, web apps).
- Include a “Features” section with 4–6 bullets (what makes it useful).
- Add a “Tech Stack” section (helps recruiters + contributors instantly).
- Provide quick install steps that work copy‑paste (no long paragraphs).
- Add a minimal “Usage” example (command/API snippet + expected output).
- Document configuration: env vars, keys, ports, config files (brief + clear).
- Include a simple folder structure so readers understand the codebase fast.
- Add a “Roadmap / TODO” (shows direction and ongoing development).
- Mention prerequisites (versions, OS, tools) to reduce setup friction.
- Link to important docs (CONTRIBUTING, LICENSE, SECURITY, wiki, demo).
- Use consistent headings and formatting (makes it readable + professional).
- Add “How to Contribute” (even 3 steps: fork → branch → PR).
- End with “License + Contact” (makes the project feel complete and credible).