Professional Markdown Documentation
Overview
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.
Core Capabilities
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
README Structure Best Practices
Essential Sections
1. Header with Badges
# Project Name
[](LICENSE)
[](releases)
[](builds)
Brief one-line description of what the project does.2. Table of Contents (for longer READMEs)
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#license)3. Features Section
## Features
- **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
## Installation
### Prerequisites
- Python 3.8 or higher
- pip package manager
### Quick Start
pip install package-name
### From Source
git clone https://github.com/username/repo.git cd repo pip install -e .
5. Usage Examples
## Usage
### Basic Example
from package import Module
Initialize
client = Module(api_key="your-key")
Perform operation
result = client.process(data) print(result)
### Advanced Usage
See [examples/](https://github.com/autumnsgrove/claudeskills/blob/HEAD/markdown-pro/examples/) directory for more detailed use cases.
6. API Documentation
## API Reference
### `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:**result = client.process( data={"key": "value"}, options={"verbose": True, "format": "json"} )
7. Contributing Section
## Contributing
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 Request8. License and Credits
## License
This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.
## Acknowledgments
- Thanks to [Contributor Name] for feature X
- Inspired by [Project Name](link)
- Built with [Technology Stack]Changelog Format
Semantic Versioning Structure
# 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).
## [Unreleased]
### Added
- New feature description
### Changed
- Modification to existing feature
### Deprecated
- Features that will be removed
### Removed
- Deleted features
### Fixed
- Bug fixes
### Security
- Security improvements
## [1.2.0] - 2025-01-15
### 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)
## [1.1.0] - 2024-12-01
### Added
- Initial release with core featuresMarkdown Formatting Best Practices
Code Blocks with Syntax Highlighting
def hello_world(): """Print hello world message.""" print("Hello, World!")
function helloWorld() { console.log("Hello, World!"); }
Install dependencies
npm install
Run tests
npm test
Tables
| Feature | Description | Status |
|---------|-------------|--------|
| Auth | User authentication | ✅ Complete |
| API | RESTful API endpoints | ✅ Complete |
| Docs | Documentation | 🚧 In Progress |
| Tests | Unit & Integration | ❌ Planned |Collapsible Sections
<details>
<summary>Click to expand advanced configuration</summary>
## Advanced Options
Configure advanced settings:
advanced: cache_size: 1000 timeout: 30 retry_attempts: 3
### Alert Boxes
Note: This feature requires Python 3.8 or higher.
Warning: This operation is irreversible!
Important: Always backup your data before upgrading.
### Links and References
<!-- External link --> Documentation
<!-- Internal link --> See Installation section.
<!-- Reference-style links --> Check out [project homepage][homepage] and [documentation][docs].
[homepage]: https://example.com [docs]: https://docs.example.com
### Images
<!-- Standard image --> Project Logo
<!-- Image with alt text and title --> Dashboard Screenshot
<!-- Linked image --> 
## Badge Creation
### Common Badge Patterns
<!-- License --> 
<!-- Version --> 
<!-- Build Status --> 
<!-- Coverage --> 
<!-- Language --> 
<!-- Platform --> 
## Helper Scripts
### Generate Table of Contents
Use the helper script to automatically generate TOC from headers:
python scripts/markdown_helper.py toc README.md
### Generate Changelog from Git
Automatically create changelog entries from git history:
python scripts/markdown_helper.py changelog --since v1.0.0 --output CHANGELOG.md
### Validate Markdown Links
Check for broken links in documentation:
python scripts/markdown_helper.py validate docs/
## Templates
### 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.
## Best Practices Summary
### 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)
## Quick Reference
### Header Hierarchy
H1 - Project Title (only one per document)
H2 - Major Sections
H3 - Subsections
H4 - Minor Points
H5 - Rare, for deep nesting
### List Formatting
<!-- Unordered -->
- Item 1
- Item 2
- Nested item - Another nested item
<!-- Ordered -->
- First step
- Second step
- Third step
<!-- Task list -->
- [x] Completed task
- [ ] Pending task
- [ ] Another pending task
### Emphasis
*italic* or _italic_ bold or __bold__ *bold italic* or ___bold italic___ ~~strikethrough~~ inline code
## Conclusion
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.