name: markdown-documentation description: Master markdown formatting, GitHub Flavored Markdown, README files, and documentation formatting. Use when writing markdown docs, READMEs, or formatting documentation.

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

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

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

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

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

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

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

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

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)

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

# 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

yarn add package-name

From source

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

Usage

Basic usage example:

import { Package } from 'package-name';

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

instance.doSomething();

Advanced Usage

More complex example:

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:

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

Configuration

Create a .configrc file:

{
  "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

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode
npm run test:watch

Deployment

# 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

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.


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


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

Create custom anchors:

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

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

Collapsible Sections

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

Hidden content goes here.

- Can include lists
- Code blocks
- Images

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

Syntax Highlighting

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

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)

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

Mermaid Diagrams

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

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

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

Formatters

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

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

Preview

# 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

$ 安裝