markdown-pro

Professional Markdown Documentation

Overview

This SKILL provides a comprehensive guide for writing professional and well-structured Markdown documentation. It covers README files, changelogs, contribution guides, and technical documentation with modern formatting, badges, and best practices applied.

Core Capabilities

README Generation

Project overview and description
Installation instructions
Usage examples including code blocks
API documentation
Badges and shields
Highlighting key features
Screenshots and demos

Changelog Automation

Semantic versioning format
Parsing Git history
Automatic release notes generation
Highlighting breaking changes
Contributor attribution

Technical Documentation

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

README Structure Best Practices

Required Sections

1. Header with Badges

# 프로젝트 이름

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-1.0.0-green.svg)](releases)
[![Build](https://img.shields.io/badge/build-passing-brightgreen.svg)](builds)

프로젝트가 무엇인지 설명하는 짧은 한 줄 설명.

2. Table of Contents (for READMEs with long content)

## 목차

- [주요 특징](#features)
- [설치 방법](#installation)
- [사용법](#usage)
- [API 참조](#api-reference)
- [기여하기](#contributing)
- [라이선스](#license)

3. Key Features Section

## 주요 특징

- **특징 1**: 장점과 함께 명확한 설명 제공
- **특징 2**: 어떤 문제를 해결하는지 기술
- **특징 3**: 독특한 강점 강조
- 크로스 플랫폼 지원 (Windows, macOS, Linux)
- 포괄적인 테스트 커버리지 (>90%)

4. Installation

## 설치 방법

### 사전 요구 사항
- Python 3.8 이상
- pip 패키지 매니저

### 빠른 시작

```bash
pip install package-name

Installing from Source

git clone https://github.com/username/repo.git
cd repo
pip install -e .


**5. 사용 예시 (Usage)**
```markdown
## 사용법

### 기본 예시

```python
from package import Module

# 초기화
client = Module(api_key="your-key")

# 작업 수행
result = client.process(data)
print(result)

Advanced Usage

For more detailed use cases, refer to the examples/ directory.


**6. API 문서화 (API Reference)**
```markdown
## API 참조

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

선택적 설정을 사용하여 입력 데이터를 처리합니다.

**매개변수:**
- `data` (str|dict): 처리할 입력 데이터
- `options` (dict, 선택 사항): 설정 옵션
  - `verbose` (bool): 상세 출력 활성화 (기본값: False)
  - `format` (str): 출력 형식 - 'json', 'yaml', 'xml' (기본값: 'json')

**반환값:**
- `dict`: 메타데이터가 포함된 처리 결과

**예외:**
- `ValueError`: 데이터가 유효하지 않은 경우
- `APIError`: API 요청이 실패한 경우

**예시:**
```python
result = client.process(
    data={"key": "value"},
    options={"verbose": True, "format": "json"}
)


**7. 기여하기 섹션 (Contributing)**
```markdown
## 기여하기

프로젝트 기여를 환영합니다! 가이드라인은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참조하세요.

### 빠른 기여 가이드
1. 저장소 포크 (Fork)
2. 피처 브랜치 생성 (`git checkout -b feature/amazing-feature`)
3. 변경 사항 커밋 (`git commit -m 'Add amazing feature'`)
4. 브랜치 푸시 (`git push origin feature/amazing-feature`)
5. 풀 리퀘스트 (Pull Request) 오픈

8. License and Credits

## 라이선스

이 프로젝트는 MIT 라이선스를 따릅니다. 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.

## 감사의 글

- 특징 X를 구현해준 [기여자 이름]님께 감사드립니다.
- [Project Name](link)에서 영감을 얻었습니다.
- [Technology Stack]으로 구축되었습니다.

Changelog Format

Semantic Versioning Structure

# 변경 이력

이 프로젝트의 모든 주목할 만한 변경 사항은 이 파일에 기록됩니다.

형식은 [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)를 따르며,
이 프로젝트는 [시맨틱 버저닝(Semantic Versioning)](https://semver.org/spec/v2.0.0.html)을 준수합니다.

## [Unreleased]

### Added
- 새로운 기능 설명

### Changed
- 기존 기능 수정 사항

### Deprecated
- 향후 삭제될 예정인 기능

### Removed
- 삭제된 기능

### Fixed
- 버그 수정

### Security
- 보안 개선 사항

## [1.2.0] - 2025-01-15

### Added
- 사용자 인증 시스템 (#123)
- CSV 내보내기 기능 (#145)
- 다크 모드 지원 (#156)

### Changed
- 응답성 개선을 위한 UI 컴포넌트 업데이트 (#134)
- 에러 메시지 개선 (#142)

### Fixed
- 백그라운드 프로세서의 메모리 누수 수정 (#139)
- 로그인 타임아웃 이슈 해결 (#148)

## [1.1.0] - 2024-12-01

### Added
- 핵심 기능을 포함한 초기 릴리스

Markdown Formatting Best Practices

Code Blocks with Syntax Highlighting

```python
def hello_world():
    """헬로 월드 메시지 출력."""
    print("Hello, World!")

function helloWorld() {
    console.log("Hello, World!");
}

# 종속성 설치
npm install

# 테스트 실행
npm test


### 표 (Tables)

```markdown
| 기능 | 설명 | 상태 |
|---------|-------------|--------|
| 인증 | 사용자 인증 시스템 | ✅ 완료 |
| API | RESTful API 엔드포인트 | ✅ 완료 |
| 문서 | 문서화 작업 | 🚧 진행 중 |
| 테스트 | 유닛 및 통합 테스트 | ❌ 계획됨 |

Collapsible Sections

<details>
<summary>클릭하여 고급 설정 확인</summary>

## 고급 옵션

고급 설정을 구성합니다:

```yaml
advanced:
  cache_size: 1000
  timeout: 30
  retry_attempts: 3

Alert Boxes

> **참고**: 이 기능은 Python 3.8 이상이 필요합니다.

> **주의**: 이 작업은 되돌릴 수 없습니다!

> **중요**: 업그레이드 전에는 항상 데이터를 백업하세요.

Links and References

<!-- 외부 링크 -->
[문서 보기](https://docs.example.com)

<!-- 내부 링크 -->
[설치 방법](#installation) 섹션을 참조하세요.

<!-- 참조 스타일 링크 -->
[프로젝트 홈페이지][homepage]와 [문서][docs]를 확인하세요.

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

Images

<!-- 표준 이미지 -->
![프로젝트 로고](assets/logo.png)

<!-- 대체 텍스트와 타이틀이 포함된 이미지 -->
![대시보드 스크린샷](screenshots/dashboard.png "메인 대시보드 화면")

<!-- 링크가 포함된 이미지 -->
[![데모 비디오](thumbnail.jpg)](https://youtube.com/watch?v=example)

Badge Generation

Common Badge Patterns

<!-- License -->
![License](https://img.shields.io/badge/license-MIT-blue.svg)

<!-- Version -->
![Version](https://img.shields.io/badge/version-1.0.0-green.svg)

<!-- Build Status -->
![Build](https://img.shields.io/badge/build-passing-brightgreen.svg)

<!-- Coverage -->
![Coverage](https://img.shields.io/badge/coverage-95%25-brightgreen.svg)

<!-- Language -->
![Python](https://img.shields.io/badge/python-3.8+-blue.svg)

<!-- Platform -->
![Platform](https://img.shields.io/badge/platform-windows%20%7C%20macOS%20%7C%20linux-lightgrey.svg)

Helper Scripts

Table of Contents (TOC) Generation

Use the helper script to automatically generate a table of contents from headers:

python scripts/markdown_helper.py toc README.md

Generating a Changelog from Git

Automatically generate changelog entries from git history:

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

Markdown Link Validation

Check for broken links in the documentation:

python scripts/markdown_helper.py validate docs/

Templates

Professional README Template

For a production-grade README template that includes all recommended sections, refer to examples/README_template.md.

Changelog Template

For a properly formatted changelog template that follows the Keep a Changelog format, refer to examples/CHANGELOG_template.mdSee

Contribution Guidelines

For a contribution guidelines template including a Code of conduct, development environment setup, and PR process, see examples/CONTRIBUTING.md.

Best Practices Summary

Do's

Use clear and descriptive headers.
Include code examples for all major features.
Add badges so the project status can be seen at a glance.
Keep line length under 100 characters for readability.
Use syntax highlighting for code blocks.
Include a table of contents for documents longer than 300 lines.
Add alt text to all images.
Provide links to related documentation.

Don'ts

Do not use generic titles such as "My Project".
Do not list long blocks of text (split them into sections).
Do not forget to update the changelog when releasing.
Do not write bare URLs (always use descriptive link text).
Do not mix header styles (maintain a consistent hierarchy).
Do not include screenshots without descriptions.
Do not hardcode version numbers here and there (use variables or badges).

Quick Reference

Header Hierarchy

# H1 - 프로젝트 제목 (문서당 하나만 사용)
## H2 - 주요 섹션
### H3 - 하위 섹션
#### H4 - 부가적인 포인트
##### H5 - 드물게 사용되는 깊은 중첩

List Formatting

<!-- 순서 없는 목록 -->
- 항목 1
- 항목 2
  - 중첩 항목
  - 또 다른 중첩 항목

<!-- 순서 있는 목록 -->
1. 첫 번째 단계
2. 두 번째 단계
3. 세 번째 단계

<!-- 작업 목록 -->
- [x] 완료된 작업
- [ ] 진행 예정 작업
- [ ] 또 다른 대기 작업

Emphasis

*기울임* 또는 _기울임_
**굵게** 또는 __굵게__
***굵은 기울임*** 또는 ___굵은 기울임___
~~취소선~~
`인라인 코드`

Conclusion

Professional Markdown documentation increases a project's accessibility, attracts contributors, and provides users with clear guidance. examples/Use the template from scripts/, and follow these best practices for polished and maintainable documentation.