markdown-pro

# 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** ```markdown # Project Name [](LICENSE) [](releases) [](builds) Brief one-line description of what the project does. ``` **2. Table of Contents** (for longer READMEs) ```markdown ## Table of Contents - [Features](#features) - [Installation](#installation) - [Usage](#usage) - [API Reference](#api-reference) - [Contributing](#contributing) - [License](#license) ``` **3. Features Section** ```markdown ## 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** ```markdown ## Installation ### 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 ## 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/](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** ```markdown ## 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 ```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). ## [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 ```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 <details> <summary>Click to expand advanced configuration</summary> ## Advanced Options Configure advanced settings: ```yaml advanced: cache_size: 1000 timeout: 30 retry_attempts: 3 ``` </details> ``` ### 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 <!-- 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 ```markdown <!-- Standard image -->  <!-- Image with alt text and title -->  <!-- Linked image --> [](https://youtube.com/watch?v=example) ``` ## Badge Creation ### Common Badge Patterns ```markdown <!-- License -->  <!-- Version -->  <!-- Build Status -->  <!-- Coverage -->  <!-- Language -->  <!-- Platform -->  ``` ## Helper Scripts ### 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/ ``` ## 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 ```markdown # H1 - Project Title (only one per document) ## H2 - Major Sections ### H3 - Subsections #### H4 - Minor Points ##### H5 - Rare, for deep nesting ``` ### List Formatting ```markdown <!-- 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 ```markdown *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.