markdown-pro
npx machina-cli add skill AutumnsGrove/ClaudeSkills/markdown-pro --openclawFiles (1)
SKILL.md
9.9 KB
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
```bash
pip install package-name
From Source
git clone https://github.com/username/repo.git
cd repo
pip install -e .
**5. Usage Examples**
```markdown
## Usage
### 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/ directory for more detailed use cases.
**6. API Documentation**
```markdown
## 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:**
```python
result = client.process(
data={"key": "value"},
options={"verbose": True, "format": "json"}
)
**7. Contributing Section**
```markdown
## 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 Request
8. 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 features
Markdown Formatting Best Practices
Code Blocks with Syntax Highlighting
```python
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
```markdown
| 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:
```yaml
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](https://docs.example.com)
<!-- Internal link -->
See [Installation](#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 -->
<!-- Image with alt text and title -->
<!-- Linked image -->
[](https://youtube.com/watch?v=example)
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 -->
1. First step
2. Second step
3. 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.
Source
git clone https://github.com/AutumnsGrove/ClaudeSkills/blob/master/markdown-pro/SKILL.mdView on GitHub Overview
This skill helps you craft professional, well-structured Markdown documentation for READMEs, changelogs, contribution guides, and technical docs. It emphasizes modern formatting, badge usage, and best practices to improve readability, navigation, and consistency across your project docs.
How This Skill Works
It provides templates and guidelines for each document type—README, changelog, API reference—so you can produce consistent structures quickly. It supports semantic changelog generation from git history, automatic table of contents, cross-references, and code-syntax highlighting to enhance readability.
When to Use It
- Starting a new project and need a polished README with badges and sections
- Automating release notes by generating a changelog from git history
- Creating long-form technical documentation with API references
- Providing contribution guidelines and a CONTRIBUTING.md with clear steps
- Adding a table of contents and cross-references for large docs
Quick Start
- Step 1: Choose a Markdown-pro template and fill in project-specific details
- Step 2: Assemble sections: Header with badges, Table of Contents, Features/Installation/Usage, API Reference
- Step 3: Enable automated changelog generation from Git history and link to releases
Best Practices
- Define a consistent header and badge set in every README
- Use a table of contents early in long READMEs
- Isolate API references in an API Reference section with clear parameters and returns
- Keep changelog entries per semantic version with breaking changes highlighted
- Use syntax-highlighted code blocks and collapsible sections for readability
Example Use Cases
- README.md with badges and installation steps
- CHANGELOG.md generated from git history
- Table of Contents for a multi-section docs
- CONTRIBUTING.md with a quick start for contributors
- API Reference section with code samples and cross-references
Frequently Asked Questions
Add this skill to your agents
