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 Link with title
Reference-style link: Link text
Automatic link: https://example.com email@example.com
Reference-style image:
Code Blocks
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
Extended Syntax (GitHub Flavored Markdown) Footnotes: Here's a sentence with a footnote1.
- 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.
Table of Contents
Features
- Feature 1
- Feature 2
- Feature 3
Demo
Try it live: https://demo.example.com
Installation
Prerequisites
- Node.js 18+
- npm or yarn
Install via npm
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
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.
## 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
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
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) Resources GitHub Markdown Guide CommonMark Spec Markdown Guide GitHub Flavored Markdown Spec Awesome README
-
This is the footnote. ↩