readme-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

README Generator

README 生成器

Generate or update a comprehensive README.md file for GitHub repositories following best practices.

遵循最佳实践，为GitHub仓库生成或更新全面的README.md文件。

Purpose

用途

This skill automates the creation of professional, well-structured README.md files for GitHub repositories. It generates all essential sections including badges for technologies used, project overview, site metrics, getting started instructions, project structure, and contact information. The skill is particularly optimized for MkDocs-based intelligent textbook projects but can be adapted for any repository type.

该Skill可自动为GitHub仓库创建专业、结构清晰的README.md文件。它会生成所有必要的板块，包括所用技术的徽章、项目概述、站点指标、快速开始指南、项目结构以及联系信息。该Skill针对基于MkDocs的智能教材项目进行了特别优化，但也可适配任何类型的仓库。

When to Use This Skill

使用场景

Use this skill when:

Starting a new GitHub repository that needs a README.md
Updating an existing README.md to follow best practices
After significant project changes that should be documented
Before publishing or sharing a repository
When migrating from another documentation system
After adding new technologies or dependencies

在以下场景中使用该Skill：

新建GitHub仓库，需要创建README.md时
更新现有README.md以符合最佳实践时
项目发生重大变更，需要更新文档时
发布或分享仓库之前
从其他文档系统迁移时
添加了新技术或依赖项后

Workflow

工作流程

Step 1: Analyze Repository Context

步骤1：分析仓库上下文

Before generating the README, gather information about the repository:

Check if README.md already exists in the root directory
Identify the repository name from
```
.git/config
```
or the working directory
Read
```
mkdocs.yml
```
if it exists to extract:
- Site name
- Site description
- Site URL (for GitHub Pages link)
- Repository URL
Check for documentation in
```
/docs
```
directory
Identify technologies used (look for package.json, requirements.txt, mkdocs.yml, etc.)

User Dialog Triggers:

If README.md exists: Ask "README.md already exists. Would you like to update it or create a backup first?"
If repository URL not found: Ask "What is the GitHub repository URL? (e.g., https://github.com/username/repo-name)"
If site URL not configured: Ask "Is this site deployed to GitHub Pages? If yes, what's the URL?"

生成README之前，先收集仓库的相关信息：

检查根目录是否已存在README.md
从
```
.git/config
```
或工作目录识别仓库名称
若存在
```
mkdocs.yml
```
，读取其中的以下信息：
- 站点名称
- 站点描述
- 站点URL（用于GitHub Pages链接）
- 仓库URL
检查
```
/docs
```
目录中的文档
识别所用技术（查看package.json、requirements.txt、mkdocs.yml等文件）

用户对话触发条件：

若已存在README.md：询问“README.md已存在。您想要更新它还是先创建备份？”
若未找到仓库URL：询问“GitHub仓库的URL是什么？（例如：https://github.com/username/repo-name）”
若未配置站点URL：询问“该站点是否部署在GitHub Pages上？如果是，URL是什么？”

Step 2: Generate Badges

步骤2：生成徽章

Create badges for all relevant technologies and platforms. Use shields.io format for consistency.

Badge Order:

MkDocs (if mkdocs.yml exists)
MkDocs Material (if theme is Material)
GitHub Pages live badge (if site is deployed)
Claude Code badge
Claude Skills badge (if .claude/skills or skills/ directory exists)
License badge
Additional technology badges (Python, JavaScript, p5.js, etc.)

Badge Templates:

markdown

[![MkDocs](https://img.shields.io/badge/Made%20with-MkDocs-526CFE?logo=materialformkdocs)](https://www.mkdocs.org/)
[![Material for MkDocs](https://img.shields.io/badge/Material%20for%20MkDocs-526CFE?logo=materialformkdocs)](https://squidfunk.github.io/mkdocs-material/)
[![GitHub Pages](https://img.shields.io/badge/View%20on-GitHub%20Pages-blue?logo=github)](SITE_URL)
[![GitHub](https://img.shields.io/badge/GitHub-OWNER%2FREPO-blue?logo=github)](REPO_URL)
[![Claude Code](https://img.shields.io/badge/Built%20with-Claude%20Code-DA7857?logo=anthropic)](https://claude.ai/code)
[![Claude Skills](https://img.shields.io/badge/Uses-Claude%20Skills-DA7857?logo=anthropic)](https://github.com/dmccreary/claude-skills)

Check for these additional badges:

p5.js:

[![p5.js](https://img.shields.io/badge/p5.js-ED225D?logo=p5.js&logoColor=white)](https://p5js.org/)

Python:

[![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white)](https://www.python.org/)

JavaScript:

[![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?logo=javascript&logoColor=black)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)

为所有相关技术和平台创建徽章。统一使用shields.io格式。

徽章顺序：

MkDocs（若存在mkdocs.yml）
MkDocs Material（若使用Material主题）
GitHub Pages在线徽章（若站点已部署）
Claude Code徽章
Claude Skills徽章（若存在.claude/skills或skills/目录）
许可证徽章
其他技术徽章（Python、JavaScript、p5.js等）

徽章模板：

markdown

[![MkDocs](https://img.shields.io/badge/Made%20with-MkDocs-526CFE?logo=materialformkdocs)](https://www.mkdocs.org/)
[![Material for MkDocs](https://img.shields.io/badge/Material%20for%20MkDocs-526CFE?logo=materialformkdocs)](https://squidfunk.github.io/mkdocs-material/)
[![GitHub Pages](https://img.shields.io/badge/View%20on-GitHub%20Pages-blue?logo=github)](SITE_URL)
[![GitHub](https://img.shields.io/badge/GitHub-OWNER%2FREPO-blue?logo=github)](REPO_URL)
[![Claude Code](https://img.shields.io/badge/Built%20with-Claude%20Code-DA7857?logo=anthropic)](https://claude.ai/code)
[![Claude Skills](https://img.shields.io/badge/Uses-Claude%20Skills-DA7857?logo=anthropic)](https://github.com/dmccreary/claude-skills)

额外徽章检查：

p5.js:

[![p5.js](https://img.shields.io/badge/p5.js-ED225D?logo=p5.js&logoColor=white)](https://p5js.org/)

Python:

[![Python](https://img.shields.io/badge/Python-3776AB?logo=python&logoColor=white)](https://www.python.org/)

JavaScript:

[![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?logo=javascript&logoColor=black)](https://developer.mozilla.org/en-US/docs/Web/JavaScript)

Step 3: Add License Badge

步骤3：添加许可证徽章

Look for license information in:

```
LICENSE
```
file in root
```
docs/license.md
```
```
mkdocs.yml
```
(copyright field)

Default to Creative Commons BY-NC-SA 4.0 if not specified:

markdown

[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-sa/4.0/)

Other common licenses:

MIT:

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Apache 2.0:

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

GPL-3.0:

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

从以下位置查找许可证信息：

根目录下的
```
LICENSE
```
文件
```
docs/license.md
```
```
mkdocs.yml
```
（copyright字段）

若未指定，默认使用知识共享BY-NC-SA 4.0许可证：

markdown

[![License: CC BY-NC-SA 4.0](https://img.shields.io/badge/License-CC%20BY--NC--SA%204.0-lightgrey.svg)](https://creativecommons.org/licenses/by-nc-sa/4.0/)

其他常见许可证：

MIT:

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

Apache 2.0:

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

GPL-3.0:

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

Step 4: Create Website Link Section

步骤4：创建网站链接板块

After badges, add a prominent link to the live website (if deployed):

markdown

undefined

徽章之后，添加醒目的在线网站链接（若已部署）：

markdown

undefined

View the Live Site

查看在线站点

Visit the interactive textbook at: https://username.github.io/repo-name

undefined

访问交互式教材：https://username.github.io/repo-name

undefined

Step 5: Write Overview/Short Description

步骤5：撰写概述/简短描述

Create a compelling 1-3 paragraph overview that answers:

What is this project?
Who is it for?
Why is it valuable?
What makes it unique or special?

Guidelines:

Keep it concise but engaging
Use active voice
Highlight key features or benefits
Mention the educational framework if applicable
For textbooks: mention target audience (grade level, prerequisites)

Example for Intelligent Textbook:

markdown

undefined

创建一段引人入胜的1-3段概述，回答以下问题：

该项目是什么？
面向哪些用户？
它的价值是什么？
它有哪些独特之处？

撰写指南：

简洁但有吸引力
使用主动语态
突出关键功能或优势
若适用，提及教育框架
对于教材：提及目标受众（年级水平、前置要求）

智能教材示例：

markdown

undefined

Overview

概述

This is an interactive, AI-generated intelligent textbook on [TOPIC] designed for [AUDIENCE]. Built using MkDocs with the Material theme, it incorporates learning graphs, concept dependencies, interactive MicroSims (p5.js simulations), and AI-assisted content generation.

The textbook follows Bloom's Taxonomy (2001 revision) for learning outcomes and uses concept dependency graphs to ensure proper prerequisite sequencing. All content is generated and curated using Claude AI skills, making it a Level 2+ intelligent textbook with interactive elements.

Whether you're a student learning [TOPIC] for the first time or an educator looking for structured course materials, this textbook provides comprehensive coverage with hands-on interactive elements that make complex concepts accessible and engaging.

undefined

这是一个针对[主题]的交互式AI生成智能教材，面向[受众]设计。它基于MkDocs和Material主题构建，整合了学习图谱、概念依赖关系、交互式MicroSims（p5.js模拟）以及AI辅助内容生成功能。

该教材遵循布鲁姆分类法（2001修订版）设定学习目标，并使用概念依赖图谱确保前置知识的合理排序。所有内容均通过Claude AI Skills生成和整理，是一款包含交互式元素的Level 2+智能教材。

无论您是首次学习[主题]的学生，还是寻找结构化课程材料的教育工作者，本教材都能提供全面的内容覆盖，以及让复杂概念变得易懂且有吸引力的交互式实践元素。

undefined

Step 6: Add Site Status and Metrics

步骤6：添加站点状态与指标

Gather and display project metrics to show completeness and scope.

Run Python script to collect metrics:

Call

scripts/collect-site-metrics.py

(or create it if needed) to gather:

Learning Graph Metrics (from
```
docs/learning-graph/
```
):
- Number of concepts in concept graph
- Quality score
- Taxonomy distribution
Content Metrics:
- Number of chapters (count directories in
```
docs/chapters/
```
  )
- Number of markdown files (
```
.md
```
  files in
```
docs/
```
  )
- Total word count (sum of all markdown files)
- Number of code blocks
- Number of lists and tables
Interactive Elements:
- Number of MicroSims (directories in
```
docs/sims/
```
  )
- Number of quizzes (files named
```
quiz.md
```
  )
- Total quiz questions (count in quiz files)
Educational Resources:
- Number of glossary terms (in
```
docs/glossary.md
```
  )
- Number of FAQ questions (in
```
docs/faq.md
```
  )
- Number of references (in
```
docs/references.md
```
  )
Media Assets:
- Number of images (
```
.png
```
  ,
```
.jpg
```
  ,
```
.svg
```
  files)
- Number of diagrams (Mermaid, vis-network)

Format as a table:

markdown

undefined

收集并展示项目指标，体现项目的完整性和规模。

运行Python脚本收集指标：

调用

scripts/collect-site-metrics.py

（若不存在则创建）以收集以下信息：

学习图谱指标（来自
```
docs/learning-graph/
```
）：
- 概念图谱中的概念数量
- 质量评分
- 分类分布
内容指标：
- 章节数量（
```
docs/chapters/
```
  中的目录数）
- Markdown文件数量（
```
docs/
```
  中的.md文件数）
- 总字数（所有Markdown文件的字数总和）
- 代码块数量
- 列表和表格数量
交互式元素：
- MicroSims数量（
```
docs/sims/
```
  中的目录数）
- 测验数量（名为quiz.md的文件数）
- 测验题目总数（测验文件中的题目数）
教育资源：
- 术语表条目数量（
```
docs/glossary.md
```
  中）
- FAQ问题数量（
```
docs/faq.md
```
  中）
- 参考文献数量（
```
docs/references.md
```
  中）
媒体资源：
- 图片数量（.png、.jpg、.svg文件）
- 图表数量（Mermaid、vis-network）

整理为表格格式：

markdown

undefined

Site Status and Metrics

站点状态与指标

Metric	Count
Concepts in Learning Graph	200
Chapters	13
Markdown Files	87
Total Words	45,230
MicroSims	12
Glossary Terms	187
FAQ Questions	42
Quiz Questions	156
Images	34
References	28

Completion Status: Approximately 85% complete (content generation phase)


**Book-Specific Metrics:**

For specialized textbooks, add domain-specific metrics:

- **Circuits textbook**: Number of circuit diagrams, simulations
- **History textbook**: Number of timelines, maps, primary source documents
- **Programming textbook**: Number of code examples, exercises, projects
- **Math textbook**: Number of equations, proofs, worked examples

指标	数量
学习图谱中的概念数	200
章节数	13
Markdown文件数	87
总字数	45,230
MicroSims数量	12
术语表条目数	187
FAQ问题数	42
测验题目数	156
图片数	34
参考文献数	28

完成状态： 约85%完成（内容生成阶段）


**教材专属指标：**

针对专业教材，添加领域专属指标：

- **电路教材**：电路图数量、模拟数量
- **历史教材**：时间线数量、地图数量、原始文献数量
- **编程教材**：代码示例数量、练习数量、项目数量
- **数学教材**：公式数量、证明数量、示例解答数量

Step 7: Add Getting Started Section

步骤7：添加快速开始板块

Provide clear instructions for using and customizing the project.

Standard sections:

Prerequisites (if any)
Clone the Repository
Installation (if dependencies needed)
Building the Site
Local Development
Deployment

Example:

markdown

undefined

提供清晰的使用和自定义项目的说明。

标准板块：

前置要求（若有）
克隆仓库
安装（若需要依赖）
构建站点
本地开发
部署

示例：

markdown

undefined

Getting Started

快速开始

Clone the Repository

克隆仓库

bash

git clone https://github.com/username/repo-name.git
cd repo-name

bash

git clone https://github.com/username/repo-name.git
cd repo-name

Install Dependencies

安装依赖

This project uses MkDocs with the Material theme:

bash

pip install mkdocs
pip install mkdocs-material

本项目使用MkDocs和Material主题：

bash

pip install mkdocs
pip install mkdocs-material

Build and Serve Locally

构建并本地运行

Build the site:

bash

mkdocs build

Serve locally for development (with live reload):

bash

mkdocs serve

Open your browser to

http://localhost:8000

构建站点：

bash

mkdocs build

本地开发（支持实时重载）：

bash

mkdocs serve

在浏览器中打开

http://localhost:8000

Deploy to GitHub Pages

部署到GitHub Pages

bash

mkdocs gh-deploy

This will build the site and push it to the

gh-pages

branch.

bash

mkdocs gh-deploy

这将构建站点并推送到

gh-pages

分支。

Using the Book

使用教材

Navigation:

Use the left sidebar to browse chapters
Click on the search icon to search all content
Each chapter includes quizzes and practice exercises

Interactive MicroSims:

Found in the "MicroSims" section
Each simulation runs standalone in your browser
Adjust parameters with sliders and controls

Customization:

Edit markdown files in
```
docs/
```
to modify content
Modify
```
mkdocs.yml
```
to change site structure
Add your own MicroSims in
```
docs/sims/
```
Customize theme in
```
docs/css/extra.css
```

undefined

导航：

使用左侧侧边栏浏览章节
点击搜索图标搜索所有内容
每个章节都包含测验和练习

交互式MicroSims：

在“MicroSims”板块中找到
每个模拟可在浏览器中独立运行
通过滑块和控件调整参数

自定义：

编辑
```
docs/
```
中的Markdown文件修改内容
修改
```
mkdocs.yml
```
更改站点结构
在
```
docs/sims/
```
中添加自己的MicroSims
在
```
docs/css/extra.css
```
中自定义主题

undefined

Step 8: Document Repository Structure

步骤8：记录仓库结构

Create an ASCII tree diagram showing the repository structure with explanatory comments.

Use this approach:

Don't list every single file
Show representative examples
Add comments explaining each major directory
Keep it concise (10-20 lines)

Example:

markdown

undefined

创建ASCII树形图，展示仓库结构并添加说明注释。

方法：

无需列出每个文件
展示代表性示例
添加注释说明每个主要目录
保持简洁（10-20行）

示例：

markdown

undefined

Repository Structure

仓库结构

repo-name/
├── docs/                          # MkDocs documentation source
│   ├── chapters/                  # Chapter content
│   │   ├── 01-intro/
│   │   │   ├── index.md          # Chapter markdown
│   │   │   └── quiz.md           # Chapter quiz
│   │   └── 02-concepts/
│   ├── sims/                      # Interactive p5.js MicroSims
│   │   ├── graph-viewer/
│   │   │   ├── main.html         # Standalone simulation
│   │   │   └── index.md          # Documentation
│   ├── learning-graph/            # Learning graph data and analysis
│   │   ├── learning-graph.csv    # Concept dependencies
│   │   ├── learning-graph.json   # vis-network format
│   │   └── quality-metrics.md    # Quality analysis
│   ├── glossary.md                # ISO 11179-compliant definitions
│   ├── faq.md                     # Frequently asked questions
│   └── references.md              # Curated references
├── skills/                        # Claude AI skills (if present)
│   └── [skill-name]/
│       ├── SKILL.md               # Skill definition
│       └── *.py                   # Supporting scripts
├── mkdocs.yml                     # MkDocs configuration
└── README.md                      # This file

undefined

repo-name/
├── docs/                          # MkDocs文档源文件
│   ├── chapters/                  # 章节内容
│   │   ├── 01-intro/
│   │   │   ├── index.md          # 章节Markdown文件
│   │   │   └── quiz.md           # 章节测验
│   │   └── 02-concepts/
│   ├── sims/                      # 交互式p5.js MicroSims
│   │   ├── graph-viewer/
│   │   │   ├── main.html         # 独立运行的模拟
│   │   │   └── index.md          # 文档说明
│   ├── learning-graph/            # 学习图谱数据与分析
│   │   ├── learning-graph.csv    # 概念依赖关系
│   │   ├── learning-graph.json   # vis-network格式
│   │   └── quality-metrics.md    # 质量分析
│   ├── glossary.md                # 符合ISO 11179标准的术语定义
│   ├── faq.md                     # 常见问题
│   └── references.md              # 精选参考文献
├── skills/                        # Claude AI Skills（若存在）
│   └── [skill-name]/
│       ├── SKILL.md               # Skill定义
│       └── *.py                   # 支持脚本
├── mkdocs.yml                     # MkDocs配置文件
└── README.md                      # 本文件

undefined

Step 9: Add Issue Reporting Section

步骤9：添加问题反馈板块

Direct users to the GitHub Issues page:

markdown

undefined

引导用户前往GitHub Issues页面：

markdown

undefined

Reporting Issues

问题反馈

Found a bug, typo, or have a suggestion for improvement? Please report it:

GitHub Issues

When reporting issues, please include:

Description of the problem or suggestion
Steps to reproduce (for bugs)
Expected vs actual behavior
Screenshots (if applicable)
Browser/environment details (for MicroSims)

undefined

发现bug、拼写错误或有改进建议？请通过以下方式反馈：

GitHub Issues

反馈问题时，请提供：

问题或建议的描述
重现步骤（针对bug）
预期行为与实际行为
截图（若适用）
浏览器/环境详情（针对MicroSims）

undefined

Step 10: Add License Information

步骤10：添加许可证信息

Reinforce licensing terms and attribution requirements:

markdown

undefined

明确许可证条款和署名要求：

markdown

undefined

License

许可证

This work is licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.

You are free to:

Share — copy and redistribute the material
Adapt — remix, transform, and build upon the material

Under the following terms:

Attribution — Give appropriate credit with a link to the original
NonCommercial — No commercial use without permission
ShareAlike — Distribute contributions under the same license

See LICENSE.md for full details.

undefined

本作品采用知识共享署名-非商业性使用-相同方式共享4.0国际许可证授权。

您可以自由地：

分享 — 复制和再分发材料
改编 — 再混合、转换和基于材料创作

但需遵守以下条款：

署名 — 必须给出适当的署名，提供指向本许可证的链接
非商业性使用 — 不得将材料用于商业用途
相同方式共享 — 若您再混合、转换或基于本材料创作，必须以相同的许可证分发您的贡献

详细信息请查看LICENSE.md。

undefined

Step 11: Add Acknowledgements

步骤11：添加致谢

Express gratitude to the open source community and key projects:

markdown

undefined

向开源社区和关键项目表达感谢：

markdown

undefined

Acknowledgements

致谢

This project is built on the shoulders of giants in the open source community:

MkDocs - Static site generator optimized for project documentation
Material for MkDocs - Beautiful, responsive theme
p5.js - Creative coding library from NYU ITP
vis-network - Network visualization library for learning graphs
Python community - Data processing and analysis tools
Claude AI by Anthropic - AI-assisted content generation
GitHub Pages - Free hosting for open source projects

Special thanks to the educators and developers who contribute to making educational resources accessible and interactive.


**Customize based on actual dependencies:**

- Add Chart.js if using bubble charts
- Add Mermaid if using diagrams
- Add specific Python libraries if used (pandas, numpy, etc.)
- Add any other key dependencies

本项目站在开源社区的巨人肩膀上构建：

MkDocs - 针对项目文档优化的静态站点生成器
Material for MkDocs - 美观的响应式主题
p5.js - 来自NYU ITP的创意编程库
vis-network - 用于学习图谱的网络可视化库
Python 社区 - 数据处理与分析工具
Claude AI by Anthropic - AI辅助内容生成
GitHub Pages - 开源项目免费托管服务

特别感谢为教育资源的可访问性和交互性做出贡献的教育工作者和开发者。


**根据实际依赖项自定义：**

- 若使用气泡图，添加Chart.js
- 若使用图表，添加Mermaid
- 若使用特定Python库（pandas、numpy等），添加进去
- 添加其他关键依赖项

Step 12: Add Contact Section

步骤12：添加联系板块

Provide a way for users to reach out:

markdown

undefined

提供用户联系的方式：

markdown

undefined

Contact

联系方式

Dan McCreary

LinkedIn: linkedin.com/in/danmccreary
GitHub: @dmccreary

Questions, suggestions, or collaboration opportunities? Feel free to connect on LinkedIn or open an issue on GitHub.


**Customize with actual maintainer information:**

- Replace with repository owner's name
- Update LinkedIn URL
- Update GitHub username
- Add email if desired (optional)
- Add website/blog if relevant

Dan McCreary

LinkedIn: linkedin.com/in/danmccreary
GitHub: @dmccreary

有问题、建议或合作机会？欢迎通过LinkedIn联系，或在GitHub上提交Issue。


**使用实际维护者信息自定义：**

- 替换为仓库所有者的姓名
- 更新LinkedIn URL
- 更新GitHub用户名
- 若需要，添加邮箱（可选）
- 添加相关网站/博客

Step 13: Add Optional Sections

步骤13：添加可选板块

Include these sections if relevant to the project:

Contributing Guidelines:

markdown

undefined

若与项目相关，可包含以下板块：

贡献指南：

markdown

undefined

Contributing

贡献

Contributions are welcome! To contribute:

Fork the repository
Create a feature branch (
```
git checkout -b feature/amazing-feature
```
)
Commit your changes (
```
git commit -m 'Add amazing feature'
```
)
Push to the branch (
```
git push origin feature/amazing-feature
```
)
Open a Pull Request

Please read CONTRIBUTING.md for detailed guidelines.


**Citation Information:**

```markdown

欢迎贡献！贡献步骤：

Fork本仓库
创建功能分支（
```
git checkout -b feature/amazing-feature
```
）
提交更改（
```
git commit -m 'Add amazing feature'
```
）
推送到分支（
```
git push origin feature/amazing-feature
```
）
打开Pull Request

详细指南请阅读CONTRIBUTING.md。


**引用信息：**

```markdown

How to Cite

引用方式

If you use this textbook in your research or teaching, please cite it as:

[Author Name]. (2024). [Textbook Title]. GitHub. https://github.com/username/repo-name

BibTeX:

bibtex

@misc{repo-name-2024,
  author = {[Author Name]},
  title = {[Textbook Title]},
  year = {2024},
  publisher = {GitHub},
  url = {https://github.com/username/repo-name}
}


**Changelog:**

```markdown

如果您在研究或教学中使用本教材，请按以下格式引用：

[作者姓名]. (2024). [教材名称]. GitHub. https://github.com/username/repo-name

BibTeX格式：

bibtex

@misc{repo-name-2024,
  author = {[作者姓名]},
  title = {[教材名称]},
  year = {2024},
  publisher = {GitHub},
  url = {https://github.com/username/repo-name}
}


**更新日志：**

```markdown

Changelog

更新日志

See CHANGELOG.md for a detailed history of changes.

Recent Updates:

v1.0.0 (2024-11-11): Initial release with 13 chapters
v0.9.0 (2024-11-01): Added 12 MicroSims and interactive elements
v0.5.0 (2024-10-15): Completed learning graph and chapter structure

undefined

详细变更历史请查看CHANGELOG.md。

近期更新：

v1.0.0 (2024-11-11): 初始版本，包含13个章节
v0.9.0 (2024-11-01): 添加12个MicroSims和交互式元素
v0.5.0 (2024-10-15): 完成学习图谱和章节结构

undefined

Step 14: Validate and Format

步骤14：验证与格式化

Step 15: Write README.md

步骤15：生成README.md

Generate the final README.md file in the repository root with all sections in order:

Title (H1) with repository name
Badges
Live site link (if applicable)
Overview
Site Status and Metrics
Getting Started
Repository Structure
Reporting Issues
License
Acknowledgements
Contact
Optional sections (Contributing, Citation, Changelog)

Formatting best practices:

Use ATX-style headers (
```
#
```
not underlines)
Include blank lines before lists
Use code fences with language specifiers
Keep lines under 120 characters where practical
Use relative links for internal documentation
Add table of contents for longer READMEs (>500 lines)

在仓库根目录生成最终的README.md文件，包含所有板块，顺序如下：

标题（H1）与仓库名称
徽章
在线站点链接（若适用）
概述
站点状态与指标
快速开始
仓库结构
问题反馈
许可证
致谢
联系方式
可选板块（贡献、引用、更新日志）

格式最佳实践：

使用ATX风格标题（
```
#
```
而非下划线）
列表前添加空行
使用带语言指定的代码块
尽可能将行长度控制在120字符以内
内部文档使用相对链接
较长的README（>500行）添加目录

Supporting Scripts

支持脚本

The skill includes Python scripts for automated metrics collection:

scripts/collect-site-metrics.py

Scans the repository and generates a metrics report including:

Markdown file count and word counts
Chapter and section counts
MicroSim count
Glossary, FAQ, quiz statistics
Image and diagram counts
Learning graph statistics

Usage:

bash

cd skills/readme-generator/scripts
python collect-site-metrics.py /path/to/repo

Output: JSON object with all metrics

scripts/validate-readme.py

Validates README.md for:

Required sections present
Working links
Valid badge URLs
Proper markdown formatting

Usage:

bash

python validate-readme.py README.md

该Skill包含用于自动收集指标的Python脚本：

scripts/collect-site-metrics.py

扫描仓库并生成指标报告，包括：

Markdown文件数量和字数
章节和板块数量
MicroSims数量
术语表、FAQ、测验统计
图片和图表数量
学习图谱统计

使用方法：

bash

cd skills/readme-generator/scripts
python collect-site-metrics.py /path/to/repo

输出：包含所有指标的JSON对象

scripts/validate-readme.py

验证README.md的以下内容：

是否包含必要板块
链接是否可用
徽章URL是否有效
Markdown格式是否正确

使用方法：

bash

python validate-readme.py README.md

Output Files

输出文件

Required:

```
README.md
```
- Complete README in repository root

Optional:

```
README-backup.md
```
- Backup of previous README (if updating)
```
docs/readme-metrics.json
```
- Metrics data in JSON format

必需文件：

```
README.md
```
- 完整的README文件，位于仓库根目录

可选文件：

```
README-backup.md
```
- 旧版README的备份（若更新）
```
docs/readme-metrics.json
```
- JSON格式的指标数据

Example Session

示例会话

User: "Generate a README for this repository"

Claude (using this skill):

Checks if README.md exists (found, create backup)
Reads
```
mkdocs.yml
```
to extract site info
Identifies technologies: MkDocs, Material, p5.js, Python
Scans
```
/docs
```
for metrics (chapters, MicroSims, glossary)
Runs
```
collect-site-metrics.py
```
to gather statistics
Generates badges for all identified technologies
Writes comprehensive README.md with all 12 sections
Validates links and formatting
Reports: "Created README.md with 15 sections, 8 badges, and current site metrics (200 concepts, 13 chapters, 87 files, 12 MicroSims). Previous README backed up to README-backup.md."

用户： "为这个仓库生成README"

Claude（使用该Skill）：

检查是否存在README.md（已找到，创建备份）
读取
```
mkdocs.yml
```
提取站点信息
识别所用技术：MkDocs、Material、p5.js、Python
扫描
```
/docs
```
目录收集指标（章节、MicroSims、术语表）
运行
```
collect-site-metrics.py
```
收集统计数据
为所有识别到的技术生成徽章
撰写包含12个板块的全面README.md
验证链接和格式
反馈："已创建README.md，包含15个板块、8个徽章和最新站点指标（200个概念、13个章节、87个文件、12个MicroSims）。旧版README已备份到README-backup.md。"

Quality Standards

质量标准

A high-quality README should have:

All relevant badges displayed correctly
Accurate, current metrics
Clear, compelling overview (200-400 words)
Complete getting started instructions
Proper attribution and licensing
Working links (100% functional)
Professional formatting
Contact information

高质量的README应具备：

所有相关徽章正确显示
准确、最新的指标
清晰、引人入胜的概述（200-400字）
完整的快速开始说明
适当的署名和许可证信息
所有链接可用（100%有效）
专业的格式
联系信息