markdown-pro

This skill provides comprehensive guidance for creating professional, well-structured Markdown documentation. It covers README files, changelogs, contribution guides, and technical documentation with modern formatting, badges, and best practices.

README Generation

• Project overview and description
• Installation instructions
• Usage examples with code blocks
• API documentation
• Badges and shields
• Feature highlights
• Screenshots and demos

Changelog Automation

• Semantic versioning format
• Git history parsing
• Automated release notes
• Breaking changes highlighting
• Contributor attribution

Technical Documentation

• Clear section hierarchy
• Code syntax highlighting
• API reference formatting
• Table of contents
• Cross-referencing
• Collapsible sections

Essential Sections

1. Header with Badges

```markdown

# Project Name

[](LICENSE)

[](releases)

[](builds)

Brief one-line description of what the project does.

```

2. Table of Contents (for longer READMEs)

```markdown

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

```

3. Features Section

```markdown

• Feature 1: Clear description with benefits
• Feature 2: What problems it solves
• Feature 3: Unique selling points
• Cross-platform support (Windows, macOS, Linux)
• Comprehensive test coverage (>90%)

```

4. Installation Instructions

```markdown

Prerequisites

• Python 3.8 or higher
• pip package manager

Quick Start

```bash

pip install package-name

```

From Source

```bash

git clone https://github.com/username/repo.git

cd repo

pip install -e .

```

```

5. Usage Examples

```markdown

Basic Example

```python

from package import Module

# Initialize

client = Module(api_key="your-key")

# Perform operation

result = client.process(data)

print(result)

```

Advanced Usage

See [examples/](examples/) directory for more detailed use cases.

```

6. API Documentation

```markdown

`Module.process(data, options=None)`

Process input data with optional configuration.

Parameters:

• data (str|dict): Input data to process
• options (dict, optional): Configuration options

- verbose (bool): Enable verbose output (default: False)

- format (str): Output format - 'json', 'yaml', 'xml' (default: 'json')

Returns:

• dict: Processed results with metadata

Raises:

• ValueError: If data is invalid
• APIError: If API request fails

Example:

```python

result = client.process(

data={"key": "value"},

options={"verbose": True, "format": "json"}

)

```

```

7. Contributing Section

```markdown

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

```

8. License and Credits

```markdown

This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.

• Thanks to [Contributor Name] for feature X
• Inspired by [Project Name](link)
• Built with [Technology Stack]

```

Semantic Versioning Structure

```markdown

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),

and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

Added

• New feature description

Changed

• Modification to existing feature

Deprecated

• Features that will be removed

Removed

• Deleted features

Fixed

• Bug fixes

Security

• Security improvements

Added

• User authentication system (#123)
• Export to CSV functionality (#145)
• Dark mode support (#156)

Changed

• Updated UI components for better responsiveness (#134)
• Improved error messages (#142)

Fixed

• Fixed memory leak in background processor (#139)
• Resolved login timeout issue (#148)

Added

• Initial release with core features

```

Code Blocks with Syntax Highlighting

```markdown

```python

def hello_world():

"""Print hello world message."""

print("Hello, World!")

```

```javascript

function helloWorld() {

console.log("Hello, World!");

}

```

```bash

# Install dependencies

npm install

# Run tests

npm test

```

```

Tables

```markdown

| Feature | Description | Status |

|---------|-------------|--------|

| Auth | User authentication | ✅ Complete |

| API | RESTful API endpoints | ✅ Complete |

| Docs | Documentation | 🚧 In Progress |

| Tests | Unit & Integration | ❌ Planned |

```

Collapsible Sections

```markdown

Configure advanced settings:

```yaml

advanced:

cache_size: 1000

timeout: 30

retry_attempts: 3

```

```

Alert Boxes

```markdown

> Note: This feature requires Python 3.8 or higher.

> Warning: This operation is irreversible!

> Important: Always backup your data before upgrading.

```

Links and References

```markdown

[Documentation](https://docs.example.com)

See [Installation](#installation) section.

Check out [project homepage][homepage] and [documentation][docs].

[homepage]: https://example.com

[docs]: https://docs.example.com

```

Images

```markdown



[](https://youtube.com/watch?v=example)

```

Common Badge Patterns

```markdown







```

Generate Table of Contents

Use the helper script to automatically generate TOC from headers:

```bash

python scripts/markdown_helper.py toc README.md

```

Generate Changelog from Git

Automatically create changelog entries from git history:

```bash

python scripts/markdown_helper.py changelog --since v1.0.0 --output CHANGELOG.md

```

Validate Markdown Links

Check for broken links in documentation:

```bash

python scripts/markdown_helper.py validate docs/

```

Professional README Template

See examples/README_template.md for a complete, production-ready README template with all recommended sections.

Changelog Template

See examples/CHANGELOG_template.md for a properly formatted changelog following Keep a Changelog format.

Contributing Guidelines

See examples/CONTRIBUTING.md for contributor guidelines template including code of conduct, development setup, and PR process.

Do's

• Use clear, descriptive headers
• Include code examples for every major feature
• Add badges for quick project status overview
• Keep line length under 100 characters for readability
• Use syntax highlighting for code blocks
• Include table of contents for documents >300 lines
• Add alt text for all images
• Link to related documentation

Don'ts

• Don't use generic titles like "My Project"
• Don't include wall-of-text paragraphs (break into sections)
• Don't forget to update changelog with releases
• Don't use bare URLs (always use descriptive link text)
• Don't mix heading styles (use consistent hierarchy)
• Don't include screenshots without descriptions
• Don't hardcode version numbers everywhere (use variables/badges)

Header Hierarchy

```markdown

# H1 - Project Title (only one per document)

H3 - Subsections

#### H4 - Minor Points

##### H5 - Rare, for deep nesting

```

List Formatting

```markdown

• Item 1
• Item 2

- Nested item

- Another nested item

1. First step
2. Second step
3. Third step

• [x] Completed task
• [ ] Pending task
• [ ] Another pending task

```

Emphasis

```markdown

italic or _italic_

bold or __bold__

bold italic or ___bold italic___

~~strikethrough~~

inline code

```

Professional Markdown documentation improves project accessibility, attracts contributors, and provides clear guidance for users. Use the templates in examples/ as starting points, customize with the helper scripts in scripts/, and follow these best practices for polished, maintainable documentation.