GitHub Markdown Guide: Master README Formatting and Documentation

Basic Markdown Syntax

These are the foundational elements you will use in every Markdown document:

Headings

Headings use hash symbols (#). One hash creates an H1 (largest), two create H2, and so on through H6. Always leave a space after the hash symbols.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4

Use a logical heading hierarchy — never skip levels. Start with one H1 for the page title, then use H2 for major sections and H3 for subsections.

Text Formatting

Links and Images

[Link Text](https://example.com)
[Link with title](https://example.com "Hover text")


![Alt text](./images/screenshot.png)
![Logo](https://example.com/logo.png)

Code Blocks and Syntax Highlighting

Code blocks are one of GFM's strongest features. Specify the language after the opening triple backticks for automatic syntax highlighting:

```javascript
function greet(name) {
    return `Hello, ${name}!`;
}
```

```python
def greet(name):
    return f"Hello, {name}!"
```

```bash
npm install && npm run build
```

GitHub supports syntax highlighting for over 200 languages. Common language identifiers include: javascript, python, bash, json, html, css, typescript, java, go, rust, sql, yaml, and diff.

Diff Syntax for Change Visualization

Use the diff language identifier to show added and removed lines with color coding:

```diff
- const oldFunction = () => {};
+ const newFunction = () => {};
  // unchanged line
```

Use our diff checker to compare text versions and generate diff output for your documentation.

Tables

GFM supports tables using pipes (|) and hyphens (-):

| Feature    | Status  | Priority |
|------------|---------|----------|
| Auth       | Done    | High     |
| Dashboard  | WIP     | Medium   |
| Reports    | Planned | Low      |

Align columns using colons in the separator row: :--- for left, :---: for center, ---: for right alignment.

Task Lists

GitHub renders checkboxes from a specific list syntax, making task lists interactive in issues and pull requests:

- [x] Set up project repository
- [x] Configure CI/CD pipeline
- [ ] Write unit tests
- [ ] Deploy to staging
- [ ] Final code review

Task lists in issue descriptions show progress bars. This makes them excellent for tracking multi-step work without creating separate issues for each item.

Collapsible Sections

Use HTML <details> and <summary> tags to create expandable sections — perfect for long logs, configuration examples, or optional information:

<details>
<summary>Click to expand detailed configuration</summary>

```json
{
    "debug": true,
    "port": 3000,
    "database": {
        "host": "localhost",
        "name": "myapp"
    }
}
```

</details>

Mermaid Diagrams

GitHub natively renders Mermaid diagrams inside code blocks, letting you create flowcharts, sequence diagrams, and other visualizations directly in Markdown:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
```

Mermaid supports flowcharts, sequence diagrams, class diagrams, Gantt charts, pie charts, and entity-relationship diagrams. This eliminates the need for external diagramming tools for many documentation scenarios.

GitHub Alerts (Admonitions)

GitHub added alert syntax for highlighting important information:

> [!NOTE]
> Background information or helpful context.

> [!TIP]
> Best practices and optimization suggestions.

> [!IMPORTANT]
> Critical steps or requirements.

> [!WARNING]
> Potential problems or breaking changes.

> [!CAUTION]
> Actions that could cause data loss.

Each type displays with a distinct color and icon. Use these instead of bold text or all-caps warnings for a professional, standardized appearance across your documentation.

Markdown Editing Tools

Frequently Asked Questions