⚡

Markdown专业文档编写 markdown-pro

Markdown专业文档编写技能，提供创建精美README、更新日志、贡献指南和技术文档的完整指南与模板。包含代码高亮、徽章生成、自动化脚本和SEO友好的结构化内容，适用于开源项目、技术文档和团队协作。关键词：Markdown文档，README生成，更新日志自动化，技术文档，代码文档，开源项目，文档模板，SEO优化。

DevOps 0 次安装 0 次浏览 更新于 3/2/2026

name: markdown-pro description: “专业的Markdown文档编写技能，用于创建精美的README文件、更新日志、贡献指南和技术文档。适用于：(1) 带有徽章和章节的README生成，(2) 基于Git历史的自动化更新日志，(3) 目录生成，(4) 贡献指南，(5) 技术文档格式化，(6) 带有语法高亮的代码文档”

专业Markdown文档编写

概述

本技能提供了创建专业、结构良好的Markdown文档的全面指导。它涵盖了README文件、更新日志、贡献指南和技术文档，包含现代格式化、徽章和最佳实践。

核心能力

README生成

  • 项目概述和描述
  • 安装说明
  • 带有代码块的使用示例
  • API文档
  • 徽章和盾牌
  • 功能亮点
  • 截图和演示

更新日志自动化

  • 语义化版本格式
  • Git历史解析
  • 自动化发布说明
  • 重大变更高亮
  • 贡献者归属

技术文档

  • 清晰的章节层次
  • 代码语法高亮
  • API参考格式化
  • 目录
  • 交叉引用
  • 可折叠章节

README结构最佳实践

基本章节

1. 带有徽章的页眉

# 项目名称

[![许可证](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![版本](https://img.shields.io/badge/version-1.0.0-green.svg)](releases)
[![构建](https://img.shields.io/badge/build-passing-brightgreen.svg)](builds)

项目功能的简要一行描述。

2. 目录（适用于较长的README）

## 目录

- [功能](#功能)
- [安装](#安装)
- [使用](#使用)
- [API参考](#api参考)
- [贡献](#贡献)
- [许可证](#许可证)

3. 功能章节

## 功能

- **功能1**：带有好处的清晰描述
- **功能2**：解决的问题
- **功能3**：独特卖点
- 跨平台支持（Windows、macOS、Linux）
- 全面的测试覆盖率（>90%）

4. 安装说明

## 安装

### 先决条件
- Python 3.8或更高版本
- pip包管理器

### 快速开始

```bash
pip install 包名

从源代码安装

git clone https://github.com/用户名/仓库.git
cd 仓库
pip install -e .


**5. 使用示例**
```markdown
## 使用

### 基础示例

```python
from 包 import 模块

# 初始化
client = 模块(api_key="你的密钥")

# 执行操作
result = client.处理(数据)
print(result)

高级用法

更多详细用例请参见examples/目录。


**6. API文档**
```markdown
## API参考

### `模块.处理(数据, 选项=None)`

使用可选配置处理输入数据。

**参数：**
- `数据` (str|dict)：要处理的输入数据
- `选项` (dict, 可选)：配置选项
  - `verbose` (bool)：启用详细输出（默认：False）
  - `format` (str)：输出格式 - 'json', 'yaml', 'xml'（默认：'json'）

**返回：**
- `dict`：带有元数据的处理结果

**抛出：**
- `ValueError`：如果数据无效
- `APIError`：如果API请求失败

**示例：**
```python
result = client.处理(
    data={"key": "value"},
    options={"verbose": True, "format": "json"}
)


**7. 贡献章节**
```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. 打开拉取请求

8. 许可证和致谢

## 许可证

本项目根据MIT许可证授权 - 详情请见[LICENSE](LICENSE)文件。

## 致谢

- 感谢[贡献者姓名]的功能X
- 灵感来源于[项目名称](链接)
- 使用[技术栈]构建

更新日志格式

语义化版本结构

# 更新日志

本项目所有显著变更将记录在此文件中。

格式基于[Keep a Changelog](https://keepachangelog.com/en/1.0.0/)，
本项目遵循[语义化版本](https://semver.org/spec/v2.0.0.html)。

## [未发布]

### 新增
- 新功能描述

### 变更
- 对现有功能的修改

### 弃用
- 将被移除的功能

### 移除
- 已删除的功能

### 修复
- 错误修复

### 安全
- 安全改进

## [1.2.0] - 2025-01-15

### 新增
- 用户认证系统 (#123)
- 导出为CSV功能 (#145)
- 深色模式支持 (#156)

### 变更
- 更新UI组件以获得更好的响应性 (#134)
- 改进错误消息 (#142)

### 修复
- 修复后台处理器中的内存泄漏 (#139)
- 解决登录超时问题 (#148)

## [1.1.0] - 2024-12-01

### 新增
- 具有核心功能的初始版本

Markdown格式化最佳实践

带有语法高亮的代码块

```python
def hello_world():
    """打印hello world消息。"""
    print("Hello, World!")

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

# 安装依赖
npm install

# 运行测试
npm test


### 表格

```markdown
| 功能 | 描述 | 状态 |
|---------|-------------|--------|
| 认证 | 用户认证 | ✅ 完成 |
| API | RESTful API端点 | ✅ 完成 |
| 文档 | 文档 | 🚧 进行中 |
| 测试 | 单元与集成 | ❌ 计划中 |

可折叠章节

<details>
<summary>点击展开高级配置</summary>

## 高级选项

配置高级设置：

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

</details>


### 提示框

```markdown
> **注意**：此功能需要Python 3.8或更高版本。

> **警告**：此操作不可逆！

> **重要**：升级前请始终备份您的数据。

链接和引用

<!-- 外部链接 -->
[文档](https://docs.example.com)

<!-- 内部链接 -->
参见[安装](#安装)章节。

<!-- 引用式链接 -->
查看[项目主页][homepage]和[文档][docs]。

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

图片

<!-- 标准图片 -->
![项目Logo](assets/logo.png)

<!-- 带有替代文本和标题的图片 -->
![仪表盘截图](screenshots/dashboard.png "主仪表盘视图")

<!-- 链接图片 -->
[![演示视频](thumbnail.jpg)](https://youtube.com/watch?v=example)

徽章创建

常见徽章模式

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

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

<!-- 构建状态 -->
![构建](https://img.shields.io/badge/build-passing-brightgreen.svg)

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

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

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

辅助脚本

生成目录

使用辅助脚本从标题自动生成目录：

python scripts/markdown_helper.py toc README.md

从Git生成更新日志

从Git历史自动创建更新日志条目：

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

验证Markdown链接

检查文档中的损坏链接：

python scripts/markdown_helper.py validate docs/

模板

专业README模板

请参阅examples/README_template.md获取包含所有推荐章节的完整、可用于生产的README模板。

更新日志模板

请参阅examples/CHANGELOG_template.md获取遵循Keep a Changelog格式的正确格式化更新日志。

贡献指南

请参阅examples/CONTRIBUTING.md获取贡献者指南模板，包括行为准则、开发设置和PR流程。

最佳实践总结

应该做的

  • 使用清晰、描述性的标题
  • 为每个主要功能包含代码示例
  • 添加徽章以快速了解项目状态
  • 为可读性保持行长度在100个字符以下
  • 为代码块使用语法高亮
  • 为超过300行的文档包含目录
  • 为所有图片添加替代文本
  • 链接到相关文档

不应该做的

  • 不要使用像“我的项目”这样的通用标题
  • 不要包含大段文本（分成章节）
  • 不要忘记在发布时更新更新日志
  • 不要使用裸URL（始终使用描述性链接文本）
  • 不要混合使用标题样式（使用一致的层次结构）
  • 不要包含没有描述的截图
  • 不要到处硬编码版本号（使用变量/徽章）

快速参考

标题层次结构

# H1 - 项目标题（每个文档仅一个）
## H2 - 主要章节
### H3 - 子章节
#### H4 - 次要点
##### H5 - 极少使用，用于深度嵌套

列表格式化

<!-- 无序 -->
- 项目1
- 项目2
  - 嵌套项目
  - 另一个嵌套项目

<!-- 有序 -->
1. 第一步
2. 第二步
3. 第三步

<!-- 任务列表 -->
- [x] 已完成任务
- [ ] 待处理任务
- [ ] 另一个待处理任务

强调

*斜体* 或 _斜体_
**粗体** 或 __粗体__
***粗斜体*** 或 ___粗斜体___
~~删除线~~
`行内代码`

结论

专业的Markdown文档提高了项目的可访问性，吸引了贡献者，并为用户提供了清晰的指导。使用examples/中的模板作为起点，使用scripts/中的辅助脚本进行自定义，并遵循这些最佳实践，以获得精美、可维护的文档。