Markdown Documentation

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

Markdown Syntax Reference

Headers

markdown

# H1 Header
## H2 Header
### H3 Header
#### H4 Header
##### H5 Header
###### H6 Header

Alternative H1
==============

Alternative H2
--------------

Text Formatting

markdown

**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 ***)

Lists

markdown

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

Links and Images

markdown

[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:
```javascript
function hello(name) {
  console.log(`Hello, ${name}!`);
}
```

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

```bash
npm install
npm start
```

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

Tables

markdown

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

Extended Syntax (GitHub Flavored Markdown)

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

README Template

markdown

# Project Name

Brief description of what this project does and who it's for.

[![Build Status](https://img.shields.io/github/workflow/status/user/repo/CI)](https://github.com/user/repo/actions)
[![License](https://img.shields.io/github/license/user/repo)](LICENSE)
[![Version](https://img.shields.io/npm/v/package-name)](https://www.npmjs.com/package/package-name)

## Table of Contents

- [Features](#features)
- [Demo](#demo)
- [Installation](#installation)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#license)
- [Contact](#contact)

## Features

- Feature 1
- Feature 2
- Feature 3

## Demo

![Demo GIF](demo.gif)

Try it live: [https://demo.example.com](https://demo.example.com)

## Installation

### Prerequisites

- Node.js 18+
- npm or yarn

### Install via npm

```bash
npm install package-name

Install via yarn

bash

yarn add package-name

From source

bash

git clone https://github.com/user/repo.git
cd repo
npm install
npm run build

Usage

Basic usage example:

javascript

import { Package } from 'package-name';

const instance = new Package({
  option1: 'value1',
  option2: 'value2'
});

instance.doSomething();

Advanced Usage

More complex example:

javascript

const result = await instance.advancedMethod({
  param1: 'value',
  param2: 123
});

console.log(result);

API Reference

`Class.method(param1, param2)`

Description of what this method does.

Parameters:

•param1 (string): Description of param1
•param2 (number): Description of param2

Returns: Description of return value

Example:

javascript

const result = instance.method('value', 42);

Configuration

Create a .configrc file:

json

{
  "setting1": "value1",
  "setting2": true,
  "setting3": {
    "nested": "value"
  }
}

Contributing

Contributions are welcome! Please follow these steps:

•Fork the repository
•Create a feature branch (git checkout -b feature/AmazingFeature)
•Commit your changes (git commit -m 'Add some AmazingFeature')
•Push to the branch (git push origin feature/AmazingFeature)
•Open a Pull Request

Please read CONTRIBUTING.md for details on our code of conduct and development process.

Testing

bash

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

Deployment

bash

# Build for production
npm run build

# Deploy
npm run deploy

Built With

•Framework 1 - Description
•Library 2 - Description
•Tool 3 - Description

Versioning

We use SemVer for versioning. For available versions, see the tags on this repository.

Authors

•Your Name - Initial work - YourUsername

See also the list of contributors who participated in this project.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

•Hat tip to anyone whose code was used
•Inspiration
•References

Support

•Documentation: https://docs.example.com
•Issues: GitHub Issues
•Discussions: GitHub Discussions
•Email: support@example.com

Roadmap

• Feature 1
• Feature 2
• Feature 3
• Feature 4

See the open issues for a full list of proposed features.

FAQ

Question 1?

Answer to question 1.

Question 2?

Answer to question 2.

Changelog

See CHANGELOG.md for a list of changes.

code


## Documentation Best Practices

### File Structure

docs/ ├── README.md ├── CONTRIBUTING.md ├── CHANGELOG.md ├── LICENSE ├── CODE_OF_CONDUCT.md ├── SECURITY.md ├── guides/ │ ├── getting-started.md │ ├── installation.md │ └── configuration.md ├── api/ │ ├── authentication.md │ ├── endpoints.md │ └── errors.md └── examples/ ├── basic-usage.md └── advanced-usage.md

code


### Linking Between Documents

```markdown
Link to another doc:
[Installation Guide](guides/installation.md)

Link to section in current doc:
[See Configuration](#configuration)

Link to section in another doc:
[API Authentication](api/authentication.md#oauth2)

Link to external resource:
[GitHub Markdown Guide](https://guides.github.com/features/mastering-markdown/)

Using Anchors

markdown

Create custom anchors:

<a name="custom-anchor"></a>
## Section Title

Link to it:
[Jump to section](#custom-anchor)

Collapsible Sections

markdown

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

Hidden content goes here.

- Can include lists
- Code blocks
- Images

```javascript
const code = 'works too';

</details> ```

Syntax Highlighting

markdown

Common languages:
```javascript
```typescript
```python
```bash
```java
```go
```rust
```sql
```json
```yaml
```html
```css
```dockerfile
```graphql
```markdown

Badges

markdown

![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)

Alerts and Callouts

markdown

> **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

Mermaid Diagrams

markdown

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

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

Markdown Tools

Linters

bash

# markdownlint
npm install -g markdownlint-cli
markdownlint '**/*.md'

# Configuration: .markdownlint.json
{
  "default": true,
  "MD013": false,
  "MD033": false
}

Formatters

bash

# prettier
npm install -g prettier
prettier --write '**/*.md'

# Configuration: .prettierrc
{
  "proseWrap": "always",
  "printWidth": 80
}

Preview

bash

# grip - GitHub README preview
pip install grip
grip README.md
# Open http://localhost:6419

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)

Markdown Documentation

Overview

When to Use

Markdown Syntax Reference

Headers

Text Formatting

Lists

Links and Images

Code Blocks

Tables

Extended Syntax (GitHub Flavored Markdown)

README Template

Install via yarn

From source

Usage

Advanced Usage

API Reference

Class.method(param1, param2)

Configuration

Contributing

Testing

Deployment

Built With

Versioning

Authors

License

Acknowledgments

Support

Roadmap

FAQ

Question 1?

Question 2?

Changelog

Using Anchors

Collapsible Sections

Syntax Highlighting

Badges

Alerts and Callouts

Mermaid Diagrams

Markdown Tools

Linters

Formatters

Preview

Best Practices

✅ DO

❌ DON'T

Resources

`Class.method(param1, param2)`