Markdown Documentation

Markdown Documentation

Table of Contents

• Overview
• When to Use
• Quick Start
• Reference Guides
• Best Practices

Overview

Master markdown syntax and best practices for creating well-formatted, readable documentation using standard Markdown and GitHub Flavored Markdown (GFM).

When to Use

• README files
• Documentation pages
• GitHub/GitLab wikis
• Blog posts
• Technical writing
• Project documentation
• Comment formatting

Quick Start

• Comment formatting

# H1 Header

## H2 Header

### H3 Header

#### H4 Header

##### H5 Header

###### H6 Header

# Alternative H1

## Alternative H2

Reference Guides

Detailed implementations in the references/ directory:

Best Practices

✅ DO

• Use descriptive link text
• Include table of contents for long documents
• Add alt text to images
• Use code blocks with language specification
• Keep lines under 80-100 characters
• Use relative links for internal docs
• Add badges for build status, coverage, etc.
• Include examples and screenshots
• Use semantic line breaks
• Test all links regularly

❌ DON'T

• Use "click here" as link text
• Forget alt text on images
• Mix HTML and Markdown unnecessarily
• Use absolute paths for local files
• Create walls of text without breaks
• Skip language specification in code blocks
• Use images for text content (accessibility)

Alerts and Callouts

Alerts and Callouts

> **Note**
> This is a note

> **Warning**
> This is a warning

> **Important**
> This is important information

GitHub-style alerts (GFM):

> [!NOTE]
> Useful information

> [!TIP]
> Helpful advice

> [!IMPORTANT]
> Key information

> [!WARNING]
> Critical content

> [!CAUTION]
> Negative potential consequences

Collapsible Sections

Collapsible Sections

````markdown <details> <summary>Click to expand</summary>

Hidden content goes here.

• Can include lists
• Code blocks
• Images

const code = "works too";

````

</details>

## Syntax Highlighting

Common languages:

````javascript

``` ````

`````

Badges

![Build Status](https://img.shields.io/github/workflow/status/user/repo/CI)
![Coverage](https://img.shields.io/codecov/c/github/user/repo)
![Version](https://img.shields.io/npm/v/package-name)
![License](https://img.shields.io/github/license/user/repo)
![Downloads](https://img.shields.io/npm/dm/package-name)
![Stars](https://img.shields.io/github/stars/user/repo?style=social)

Extended Syntax (GitHub Flavored Markdown)

Extended Syntax (GitHub Flavored Markdown)

Footnotes:
Here's a sentence with a footnote[^1].

[^1]: This is the footnote.

Definition list:
Term
: Definition

Emoji:
:smile: :rocket: :heart:
:+1: :-1: :eyes:

Automatic URL linking:
https://github.com

Task lists in issues:

- [x] #739
- [ ] https://github.com/octo-org/repo/issues/1
- [ ] Add tests

Mentioning users and teams:
@username
@org/team-name

Referencing issues and PRs:
#123
GH-123
username/repo#123

Links and Images

Links and Images

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

Reference-style link:
[Link text][reference]
[reference]: https://example.com

Automatic link:
<https://example.com>
<email@example.com>

![Alt text](image.png)
![Alt text](image.png "Image title")

Reference-style image:
![Alt text][image-ref]
[image-ref]: image.png

Code Blocks

```markdown Inline code: const x = 5;`

Code block with language:

function hello(name) {
  console.log(`Hello, ${name}!`);
}

def hello(name):
    print(f"Hello, {name}!")

npm install
npm start

Indented code block (4 spaces): const x = 5; console.log(x); ````

Tables

Simple table:
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1 | Data | Data |
| Row 2 | Data | Data |

Aligned columns:
| Left | Center | Right |
|:-----|:------:|------:|
| Left | Center | Right |
| Text | Text | Text |

Minimal table:
Column 1 | Column 2
---------|----------
Data | Data
Data | Data

Lists

Lists

Unordered list:

- Item 1
- Item 2
  - Nested item 2.1
  - Nested item 2.2
- Item 3

Using asterisks:

- Item 1
- Item 2

Using plus:

- Item 1
- Item 2

Ordered list:

1. First item
2. Second item
   1. Nested item 2.1
   2. Nested item 2.2
3. Third item

Task list (GitHub Flavored Markdown):

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Mermaid Diagrams

Mermaid Diagrams

````markdown

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do Something]
    B -->|No| D[Do Something Else]
    C --> E[End]
    D --> E

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob!
    B->>A: Hello Alice!

`````

Text Formatting

Text Formatting

**Bold text**
**Also bold**

_Italic text_
_Also italic_

**_Bold and italic_**
**_Also bold and italic_**

~~Strikethrough~~

`Inline code`

> Blockquote
> Multiple lines
> in blockquote

---

Horizontal rule (also \_\_\_ or \*\*\*)

Document Title

Overview

TODO: Brief description of this document's purpose.

Prerequisites

• TODO: List prerequisites

Getting Started

TODO: Step-by-step instructions.

Configuration

TODO: Configuration details.

Examples

TODO: Add practical examples.

Troubleshooting

TODO: Common issues and solutions.

References

• TODO: Add relevant links