book-metrics-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Book Metrics Generator

教材指标生成器

Overview

概述

This skill automates the generation of comprehensive metrics for intelligent textbooks. It analyzes the entire textbook structure and content to produce two detailed reports:

book-metrics.md - Overall book statistics with links to relevant sections
chapter-metrics.md - Chapter-by-chapter breakdown in tabular format

The metrics provide quantitative insights into content volume, educational components, and interactive elements, helping authors track progress and identify areas needing attention.

本Skill可自动为智能教材生成全面的指标。它会分析整个教材的结构和内容，生成两份详细报告：

book-metrics.md - 包含教材整体统计数据及相关章节链接
chapter-metrics.md - 以表格形式呈现的按章节细分数据

这些指标可提供关于内容体量、教学组件和互动元素的定量洞察，帮助作者跟踪进度并识别需要关注的领域。

Running the Shell Script Directly

直接运行Shell脚本

Tell the user the following:

We setup this skill mostly to automate the process of installing the shell script. The shell script calls a Python program that does the work of building the metrics files. If you want to save a few tokens, after the skill is installed (a symbolic link really) you can run the following from your terminal:

~/.claude/skills/book-metrics-generator/scripts/book-metrics-generator.sh

Just make sure that you do a git pull on the claude-skills repo to get the latest version.

请告知用户以下内容：

我们设置本Skill主要是为了自动化安装Shell脚本的流程。该Shell脚本会调用一个Python程序来生成指标文件。如果您想节省一些token，在Skill安装完成后（实际是创建符号链接），可以在终端中运行以下命令：

~/.claude/skills/book-metrics-generator/scripts/book-metrics-generator.sh

请确保您已对claude-skills仓库执行git pull操作以获取最新版本。

When to Use This Skill

使用场景

Use this skill when:

Tracking progress on intelligent textbook development
Preparing status reports for stakeholders or collaborators
Assessing content completeness before publication
Analyzing the distribution of educational elements across chapters
Estimating the physical page equivalent of the digital textbook
Auditing content after major updates or additions
Comparing metrics over time to track growth

The skill is designed for MkDocs Material-based intelligent textbooks following the structure defined in the intelligent-textbook skill.

在以下场景中使用本Skill：

跟踪智能教材的开发进度
为利益相关者或合作者准备状态报告
在发布前评估内容完整性
分析教学元素在各章节的分布情况
估算数字教材对应的实体书页数
在重大更新或内容添加后审核内容
对比不同时间点的指标以跟踪内容增长

本Skill专为遵循intelligent-textbook Skill定义的结构、基于MkDocs Material构建的智能教材设计。

Prerequisites

前置条件

The intelligent textbook project should have:

A
```
docs/
```
directory containing the textbook content
A
```
docs/chapters/
```
directory with chapter subdirectories (e.g.,
```
01-chapter-name/
```
,
```
02-chapter-name/
```
)
Each chapter directory containing an
```
index.md
```
file
A
```
docs/learning-graph/
```
directory (will be created if it doesn't exist)

Optional components that enhance metrics:

```
docs/learning-graph/learning-graph.csv
```
- For concept counting
```
docs/glossary.md
```
- For glossary term counting
```
docs/faq.md
```
- For FAQ counting
```
docs/sims/
```
- For MicroSim counting
Chapter-level
```
quiz.md
```
files - For quiz question counting

智能教材项目需满足：

包含存放教材内容的
```
docs/
```
目录
包含带有章节子目录的
```
docs/chapters/
```
目录（例如
```
01-chapter-name/
```
、
```
02-chapter-name/
```
）
每个章节目录中包含
```
index.md
```
文件
包含
```
docs/learning-graph/
```
目录（若不存在，脚本会自动创建）

可增强指标分析的可选组件：

```
docs/learning-graph/learning-graph.csv
```
- 用于统计概念数量
```
docs/glossary.md
```
- 用于统计术语表词条数量
```
docs/faq.md
```
- 用于统计FAQ数量
```
docs/sims/
```
- 用于统计MicroSims数量
各章节的
```
quiz.md
```
文件 - 用于统计测验题目数量

Usage

使用方法

Basic Workflow

基础工作流

To generate metrics for an intelligent textbook:

Navigate to the textbook project root directory
Execute the shell script:

bash

./scripts/book-metrics-generator.sh

Or if the skill scripts are available:

bash

bash /path/to/skill/scripts/book-metrics-generator.sh

Review the generated files:

```
docs/learning-graph/book-metrics.md
```
```
docs/learning-graph/chapter-metrics.md
```

Update
```
mkdocs.yml
```
navigation to include the new metrics files:

yaml

nav:
  - Learning Graph:
    - Book Metrics: learning-graph/book-metrics.md
    - Chapter Metrics: learning-graph/chapter-metrics.md

要为智能教材生成指标：

导航至教材项目的根目录
执行Shell脚本：

bash

./scripts/book-metrics-generator.sh

或者，如果Skill脚本已可用：

bash

bash /path/to/skill/scripts/book-metrics-generator.sh

查看生成的文件：

```
docs/learning-graph/book-metrics.md
```
```
docs/learning-graph/chapter-metrics.md
```

更新
```
mkdocs.yml
```
的导航配置以包含新生成的指标文件：

yaml

nav:
  - 学习图谱:
    - 教材指标: learning-graph/book-metrics.md
    - 章节指标: learning-graph/chapter-metrics.md

Custom Docs Directory

自定义Docs目录

To analyze a textbook in a non-standard location:

bash

./scripts/book-metrics-generator.sh path/to/custom/docs

要分析非标准位置的教材：

bash

./scripts/book-metrics-generator.sh path/to/custom/docs

Running the Python Script Directly

直接运行Python脚本

For more control or integration into custom workflows:

bash

python3 scripts/book-metrics.py docs

如需更多控制权或集成到自定义工作流中：

bash

python3 scripts/book-metrics.py docs

Book Metrics Collected

收集的教材指标

The book-metrics.md file contains a four-column table with the following metrics:

Category	Metric	Description
Structure	Chapters	Count of chapter directories with index.md files
Learning	Concepts	Number of concepts in learning-graph.csv
Learning	Glossary Terms	Count of defined terms (H2/H3 headers in glossary.md)
Learning	FAQs	Number of FAQ items (H2 headers in faq.md)
Assessment	Quiz Questions	Total quiz questions across all chapters
Visual	Diagrams	Count of H4 headers starting with "#### Diagram:"
Technical	Equations	LaTeX expressions using $ and $$ delimiters
Interactive	MicroSims	Directories in docs/sims/ with index.md files
Content	Total Words	All words in markdown files (excluding code and URLs)
Content	Links	Markdown-formatted hyperlinks text
Estimation	Equivalent Pages	Calculated pages based on words + visuals

book-metrics.md文件包含一个四列表格，包含以下指标：

类别	指标	描述
结构	章节数	包含index.md文件的章节目录数量
学习	概念数	learning-graph.csv中的概念数量
学习	术语表词条数	已定义的术语数量（glossary.md中的H2/H3标题）
学习	FAQ数量	FAQ条目数量（faq.md中的H2标题）
评估	测验题目数	所有章节的测验题目总数
可视化	图表数	以"#### Diagram:"开头的H4标题数量
技术	公式数	使用$和$$分隔符的LaTeX表达式数量
互动	MicroSims数	docs/sims/中包含index.md文件的目录数量
内容	总字数	所有Markdown文件中的字数（排除代码和URL）
内容	链接数	Markdown格式的超链接text数量
估算	等效页数	根据字数和可视化元素计算得出的页数

Page Calculation Formula

页数计算公式

Equivalent pages are estimated using:

Pages = (Total Words ÷ 250) + (Diagrams × 0.25) + (MicroSims × 0.5)

Assumptions:

250 words per printed page
Each diagram occupies 0.25 page
Each MicroSim occupies 0.5 page

等效页数的估算公式：

页数 = (总字数 ÷ 250) + (图表数 × 0.25) + (MicroSims数 × 0.5)

假设条件：

每页印刷版包含250个单词
每个图表占0.25页
每个MicroSim占0.5页

Chapter Metrics Collected

收集的章节指标

The chapter-metrics.md file contains a table with these columns:

Column	Description
Chapter	Chapter number (leading zeros removed)
Name	Chapter title extracted from index.md H1 header
Sections	Count of H2 and H3 headers in chapter markdown files
Diagrams	Count of "#### Diagram:" headers in chapter
Words	Total word count for all markdown in the chapter

This table enables quick identification of:

Chapters with insufficient content
Uneven content distribution
Chapters lacking visual aids
Outlier chapters requiring review

chapter-metrics.md文件包含一个表格，包含以下列：

列	描述
章节	章节编号（去除前导零）
名称	从index.md的H1标题提取的章节标题
小节数	章节Markdown文件中的H2和H3标题数量
图表数	章节中的图表数量
字数	章节所有Markdown文件的总字数

该表格可快速识别：

内容不足的章节
内容分布不均的情况
缺乏可视化辅助的章节
需要审核的异常章节

Technical Details

技术细节

File Detection Patterns

文件检测规则

The Python script uses these patterns to count elements:

Chapters: Directories in
```
docs/chapters/
```
containing
```
index.md
```
Concepts: Rows in
```
docs/learning-graph/learning-graph.csv
```
(excluding header)
Glossary Terms:
```
^##
```
and
```
^###
```
patterns in
```
glossary.md
```
FAQs:
```
^##
```
pattern in
```
faq.md
```
Quiz Questions:
```
^##
```
pattern in all
```
quiz.md
```
files
Diagrams:
```
^####\s+Diagram:
```
pattern (multiline flag)
Equations:
```
\$[^$]+\$
```
(inline) and
```
\$\$[^$]+\$\$
```
(display)
MicroSims: Subdirectories in
```
docs/sims/
```
with
```
index.md
```
Links:
```
\[([^\]]+)\]$([^)]+)$
```
pattern

Python脚本使用以下规则统计各类元素：

章节：
```
docs/chapters/
```
目录下包含
```
index.md
```
的目录
概念：
```
docs/learning-graph/learning-graph.csv
```
中的行数（排除表头）
术语表词条：
```
glossary.md
```
中的
```
^##
```
和
```
^###
```
模式
FAQ：所有
```
faq.md
```
文件中的
```
^##
```
模式
测验题目：所有
```
quiz.md
```
文件中的
```
^##
```
模式
图表：
```
^####\s+Diagram:
```
模式（支持多行）
公式：
```
\$[^$]+\$
```
（行内）和
```
\$\$[^$]+\$\$
```
（块级）
MicroSims：
```
docs/sims/
```
下包含
```
index.md
```
的子目录
链接：
```
\[([^\]]+)\]$([^)]+)$
```
模式

Word Counting Methodology

字数统计方法

To ensure accurate word counts, the script:

Removes code blocks (triple backticks)
Removes inline code (single backticks)
Removes URLs (http/https links)
Counts word boundaries using
```
\b\w+\b
```
pattern

为确保字数统计准确，脚本会：

移除代码块（三个反引号包裹的内容）
移除行内代码（单个反引号包裹的内容）
移除URL（http/https链接）
使用
```
\b\w+\b
```
模式统计单词边界

Error Handling

错误处理

The script gracefully handles:

Missing directories (returns 0 for counts)
Missing files (returns 0 for counts)
Malformed CSV files (prints warning, returns 0)
Encoding issues (UTF-8 with fallback)
Permission errors (prints warning, continues)

脚本可优雅处理以下情况：

缺失的目录（统计数返回0）
缺失的文件（统计数返回0）
格式错误的CSV文件（打印警告，返回0）
编码问题（使用UTF-8编码并提供降级方案）
权限错误（打印警告，继续执行）

Extending the Metrics

扩展指标

Adding New Book-Level Metrics

添加新的教材级指标

To add a new book-level metric:

Add a counting method to the
```
BookMetricsGenerator
```
class:

python

def count_new_metric(self) -> int:
    """Count the new metric.

    Returns:
        Number of items
    """
    # Implementation here
    pass

Update
```
generate_book_metrics_md()
```
to call the new method:

python

new_metric = self.count_new_metric()

Add a row to the markdown table:

python

md += f"| New Metric | {new_metric} | [Link](path) | Description |\n"

Add explanation in the "Metrics Explanation" section

要添加新的教材级指标：

向
```
BookMetricsGenerator
```
类添加统计方法：

python

def count_new_metric(self) -> int:
    """统计新指标。

    返回:
        元素数量
    """
    # 实现代码
    pass

更新
```
generate_book_metrics_md()
```
以调用新方法：

python

new_metric = self.count_new_metric()

向Markdown表格添加一行：

python

md += f"| 新指标 | {new_metric} | [链接](path) | 描述 |\n"

在“指标说明”部分添加解释

Adding New Chapter-Level Metrics

添加新的章节级指标

To add a new chapter-level metric:

Update
```
get_chapter_metrics()
```
to compute the new metric:

python

def get_chapter_metrics(self, chapter: Dict[str, Any]) -> Dict[str, Any]:
    # Existing code...

    # Add new metric
    new_metric = self.count_new_metric_for_chapter(chapter)

    return {
        # Existing fields...
        'new_metric': new_metric
    }

Update
```
generate_chapter_metrics_md()
```
to include the new column:

python

md += "| Chapter | Name | ... | New Metric |\n"

要添加新的章节级指标：

更新
```
get_chapter_metrics()
```
以计算新指标：

python

def get_chapter_metrics(self, chapter: Dict[str, Any]) -> Dict[str, Any]:
    # 现有代码...

    # 添加新指标
    new_metric = self.count_new_metric_for_chapter(chapter)

    return {
        # 现有字段...
        'new_metric': new_metric
    }

更新
```
generate_chapter_metrics_md()
```
以包含新列：

python

md += "| 章节 | 名称 | ... | 新指标 |\n"

In the row loop:

在行循环中:

md += f"| {metrics['number']} | ... | {metrics['new_metric']} |\n"


3. Add explanation in the "Metrics Explanation" section

md += f"| {metrics['number']} | ... | {metrics['new_metric']} |\n"


3. 在“指标说明”部分添加解释

Integration with Workflows

工作流集成

After Content Generation

内容生成后

Run metrics generation after completing chapters:

bash

undefined

在完成章节内容生成后运行指标生成：

bash

undefined

Generate chapter content

生成章节内容

/skill intelligent-textbook

Generate metrics

生成指标

/skill book-metrics-generator

Review progress

查看进度

cat docs/learning-graph/book-metrics.md

undefined

cat docs/learning-graph/book-metrics.md

undefined

Continuous Integration

持续集成

Add to

.github/workflows/metrics.yml

yaml

name: Generate Metrics

on:
  push:
    paths:
      - 'docs/**/*.md'

jobs:
  metrics:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Generate metrics
        run: python3 scripts/book-metrics.py docs
      - name: Commit metrics
        run: |
          git config user.name "GitHub Actions"
          git add docs/learning-graph/book-metrics.md
          git add docs/learning-graph/chapter-metrics.md
          git commit -m "Update metrics" || exit 0
          git push

添加到

.github/workflows/metrics.yml

：

yaml

name: Generate Metrics

on:
  push:
    paths:
      - 'docs/**/*.md'

jobs:
  metrics:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Generate metrics
        run: python3 scripts/book-metrics.py docs
      - name: Commit metrics
        run: |
          git config user.name "GitHub Actions"
          git add docs/learning-graph/book-metrics.md
          git add docs/learning-graph/chapter-metrics.md
          git commit -m "Update metrics" || exit 0
          git push

Pre-Deployment Checklist

部署前检查清单

Before deploying the textbook:

Run metrics generation
Verify all chapters have reasonable word counts (>1000 words)
Check that quiz questions exist for most chapters
Ensure MicroSims cover key concepts
Review total page count for scope appropriateness

部署教材前：

运行指标生成
验证所有章节的字数合理（>1000字）
检查大多数章节是否包含测验题目
确保MicroSims覆盖关键概念
查看总页数是否符合范围要求

Troubleshooting

故障排除

No Chapters Found

未找到章节

Symptom: "No chapters found" in chapter-metrics.md

Solution: Ensure chapter directories:

Are located in
```
docs/chapters/
```
Contain an
```
index.md
```
file
Follow naming pattern:
```
NN-chapter-name/
```
(where NN is a number)

症状：chapter-metrics.md中显示“未找到章节”

解决方案：确保章节目录：

位于
```
docs/chapters/
```
目录下
包含
```
index.md
```
文件
遵循命名模式：
```
NN-chapter-name/
```
（NN为数字）

Concept Count is Zero

概念数为零

Symptom: Concepts metric shows 0

Solution: Verify that:

```
docs/learning-graph/learning-graph.csv
```
exists
CSV file has correct format (header row + data rows)
CSV file is UTF-8 encoded

症状：概念指标显示为0

解决方案：验证：

```
docs/learning-graph/learning-graph.csv
```
文件存在
CSV文件格式正确（包含表头行和数据行）
CSV文件为UTF-8编码

Missing Metrics Files

指标文件缺失

Symptom: Metrics files not created

Solution: Check that:

```
docs/learning-graph/
```
directory exists (script creates it if missing)
User has write permissions to the directory
Python 3 is installed and accessible via
```
python3
```
command

症状：未生成指标文件

解决方案：检查：

```
docs/learning-graph/
```
目录是否存在（脚本会自动创建不存在的目录）
用户对该目录有写入权限
已安装Python 3且可通过
```
python3
```
命令访问

Incorrect Word Counts

字数统计错误

Symptom: Word counts seem too high or too low

Solution: The script excludes code blocks and URLs. To verify:

Check for large code blocks that should be excluded
Review markdown files for formatting issues
Ensure no binary or non-text files with .md extension

症状：字数统计过高或过低

解决方案：脚本会排除代码块和URL。要验证：

检查是否有应被排除的大型代码块
查看Markdown文件是否存在格式问题
确保没有扩展名为.md的二进制或非文本文件

Resources

资源

scripts/

This skill includes two executable scripts:

本Skill包含两个可执行脚本：

book-metrics-generator.sh

Bash wrapper script that:

Validates the docs directory exists
Checks for Python 3 installation
Executes the Python metrics generator
Provides user-friendly output

Default usage assumes

docs/

directory in current working directory.

Bash包装脚本，功能：

验证docs目录是否存在
检查Python 3是否已安装
执行Python指标生成器
提供用户友好的输出

默认使用场景为当前工作目录下的

docs/

目录。

book-metrics.py

Python 3 script that:

Implements modular
```
BookMetricsGenerator
```
class
Provides separate methods for each metric type
Generates markdown-formatted output
Handles errors gracefully with warnings
Supports custom docs directory path

The Python script is designed for extensibility - new metrics can be added by implementing new counting methods and updating the markdown generation functions.

Python 3脚本，功能：

实现模块化的
```
BookMetricsGenerator
```
类
为每种指标类型提供独立方法
生成Markdown格式的输出
优雅地处理错误并给出警告
支持自定义docs目录路径

Python脚本具有可扩展性——通过实现新的统计方法并更新Markdown生成函数，即可添加新指标。

Example Output

输出示例

Book Metrics Table Sample

教材指标表格示例

markdown

| Metric Name | Value | Link | Notes |
|-------------|-------|------|-------|
| Chapters | 12 | [Chapters](../chapters/) | Number of chapter directories |
| Concepts | 200 | [Learning Graph](learning-graph.csv) | Concepts from learning graph |
| Total Words | 45,000 | - | Words in all markdown files |
| Equivalent Pages | 195 | - | Estimated pages (250 words/page + visuals) |

markdown

| 指标名称 | 数值 | 链接 | 说明 |
|-------------|-------|------|-------|
| 章节数 | 12 | [章节](../chapters/) | 章节目录数量 |
| 概念数 | 200 | [学习图谱](learning-graph.csv) | 来自学习图谱的概念数量 |
| 总字数 | 45,000 | - | 所有Markdown文件中的字数 |
| 等效页数 | 195 | - | 估算页数（每页250字 + 可视化元素） |

Chapter Metrics Table Sample

章节指标表格示例

markdown

| Chapter | Name | Sections | Diagrams | Words |
|---------|------|----------|----------|-------|
| 1 | Introduction to Geometry | 8 | 3 | 3,200 |
| 2 | Points and Lines | 12 | 7 | 4,100 |
| 3 | Angles and Triangles | 15 | 12 | 5,500 |

markdown

| 章节 | 名称 | 小节数 | 图表数 | 字数 |
|---------|------|----------|----------|-------|
| 1 | 几何入门 | 8 | 3 | 3,200 |
| 2 | 点与线 | 12 | 7 | 4,100 |
| 3 | 角与三角形 | 15 | 12 | 5,500 |