# mkdocs-statistics-plugin
一个用于 mkdocs 文档统计的插件，包括全局页面数、字数、代码块行数，单页字数、代码行数、预计阅读时间等。
预览：<https://note.tonycrane.cc/>（只有带评论的页面有单页统计）
## 安装
可以通过 pypi 直接安装：
```shell
$ pip install mkdocs-statistics-plugin
```
也可以从源码安装
```shell
$ git clone https://github.com/TonyCrane/mkdocs-statistics-plugin.git
$ cd mkdocs-statistics-plugin
$ pip install . # or pip install -e .
```
## 使用
- 在 mkdocs.yml 中启用插件：
```yaml
plugins:
- statistics
```
配置选项及解释：
| 选项 | 类型 | 默认值 | 解释 |
|:----|:----|:----|:----|
|`pages_placeholder`|str|`\{\{\s*pages\s*\}\}`|全局统计页面中页面数占位符（正则）|
|`words_placeholder`|str|`\{\{\s*words\s*\}\}`|全局统计页面中字数占位符（正则）|
|`codes_placeholder`|str|`\{\{\s*codes\s*\}\}`|全局统计页面中代码行数占位符（正则）|
|`page_statistics`|bool|`True`|是否在单页中显示统计信息|
|`page_check_metadata`|str||如果为空，则所有页面都显示；否则包含指定 metadata 才显示单页统计信息|
|`page_read_time`|bool|`True`|是否显示单页预计阅读时间|
|`page_template`|str||单页统计信息模板相对路径（相对 docs）|
|`words_per_minute`|int|`300`|每分钟预计阅读字数|
|`codelines_per_minute`|int|`80`|每分钟预计阅读代码行数|
### 几种使用方式
#### 全局统计页
例如在首页显示全局统计信息。需要在该页面的元数据中添加：
```yaml
---
statistics: True
---
```
然后在该页中需要的部分添加占位符，例如：
```markdown
本站共有 {{ pages }} 个页面，{{ words }} 个字，{{ codes }} 行代码。
```
#### 单页统计
需要按照上述选项填写好配置（默认开启单页统计，且~~应该可以~~适配 material 主题）。
如果 `page_check_metadata` 为空，则所有页面都显示单页统计信息；否则包含指定 metadata 才显示单页统计信息。例如在我自己的设置中，包含 `comment` 的页面才显示单页统计信息（且包含 `nostatistics` 的页面不显示统计信息）：
```yaml
plugins:
- statistics:
page_check_metadata: comment
```
### 高级用法
#### 自定义单页统计模板
可以通过 `page_template` 选项指定单页统计模板的相对路径（相对 docs）。这个模板会被插入到 markdown 源码的一级标题下方，会传入 `words` `code_lines` `read_time`（可选）三个模板参数。
自定义的话可以参考提供的模板。
#### 阅读时间
可以通过 `page_read_time` 选项控制是否显示单页预计阅读时间。默认开启。
阅读时间的计算方式是分别计算字数和代码行数的阅读时间，然后取二者之和。可以通过 `words_per_minute` 和 `codelines_per_minute` 选项分别设置每分钟预计阅读字数和代码行数。默认情况下分别为 300 和 80，对于技术类文章这样的设置基本合理，对于其他类型例如文学类文章每分钟阅读字数应该提高到 400~600 左右较为合理。
~~计划添加页面元信息选项来为单页设置特定的阅读时间。（咕咕咕）~~
#### 字数统计细节
本插件的字数统计细节为：一个英文单词（包括数字）算一个字，一个中文汉字算一个字，标点都不算字；代码块（带语言的三反引号语法）中所有内容都不计入字数，而是计入代码块行数统计。
具体细节见 plugin.py 中的 \_clean\_markdown 方法。
## 开发
可能很不稳定（反正至少我能跑起来），有任何问题欢迎 issue 提出。同时页欢迎任何 PR，尽管提就好。
Raw data
{
"_id": null,
"home_page": "https://github.com/TonyCrane/mkdocs-statistics-plugin",
"name": "mkdocs-statistics-plugin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "mkdocs python markdown statistics",
"author": "TonyCrane",
"author_email": "me@tonycrane.cc",
"download_url": "https://files.pythonhosted.org/packages/08/76/093726a1881802ededb66fa7e028beeb0e655a96a5f6d8789ea617c0ce5b/mkdocs-statistics-plugin-0.1.2.tar.gz",
"platform": null,
"description": "# mkdocs-statistics-plugin\n\n\u4e00\u4e2a\u7528\u4e8e mkdocs \u6587\u6863\u7edf\u8ba1\u7684\u63d2\u4ef6\uff0c\u5305\u62ec\u5168\u5c40\u9875\u9762\u6570\u3001\u5b57\u6570\u3001\u4ee3\u7801\u5757\u884c\u6570\uff0c\u5355\u9875\u5b57\u6570\u3001\u4ee3\u7801\u884c\u6570\u3001\u9884\u8ba1\u9605\u8bfb\u65f6\u95f4\u7b49\u3002\n\n\u9884\u89c8\uff1a<https://note.tonycrane.cc/>\uff08\u53ea\u6709\u5e26\u8bc4\u8bba\u7684\u9875\u9762\u6709\u5355\u9875\u7edf\u8ba1\uff09\n\n## \u5b89\u88c5\n\u53ef\u4ee5\u901a\u8fc7 pypi \u76f4\u63a5\u5b89\u88c5\uff1a\n```shell\n$ pip install mkdocs-statistics-plugin\n```\n\n\u4e5f\u53ef\u4ee5\u4ece\u6e90\u7801\u5b89\u88c5\n\n```shell\n$ git clone https://github.com/TonyCrane/mkdocs-statistics-plugin.git\n$ cd mkdocs-statistics-plugin\n$ pip install . # or pip install -e .\n```\n\n## \u4f7f\u7528\n- \u5728 mkdocs.yml \u4e2d\u542f\u7528\u63d2\u4ef6\uff1a\n ```yaml\n plugins:\n - statistics\n ```\n\n\u914d\u7f6e\u9009\u9879\u53ca\u89e3\u91ca\uff1a\n\n| \u9009\u9879 | \u7c7b\u578b | \u9ed8\u8ba4\u503c | \u89e3\u91ca |\n|:----|:----|:----|:----|\n|`pages_placeholder`|str|`\\{\\{\\s*pages\\s*\\}\\}`|\u5168\u5c40\u7edf\u8ba1\u9875\u9762\u4e2d\u9875\u9762\u6570\u5360\u4f4d\u7b26\uff08\u6b63\u5219\uff09|\n|`words_placeholder`|str|`\\{\\{\\s*words\\s*\\}\\}`|\u5168\u5c40\u7edf\u8ba1\u9875\u9762\u4e2d\u5b57\u6570\u5360\u4f4d\u7b26\uff08\u6b63\u5219\uff09|\n|`codes_placeholder`|str|`\\{\\{\\s*codes\\s*\\}\\}`|\u5168\u5c40\u7edf\u8ba1\u9875\u9762\u4e2d\u4ee3\u7801\u884c\u6570\u5360\u4f4d\u7b26\uff08\u6b63\u5219\uff09|\n|`page_statistics`|bool|`True`|\u662f\u5426\u5728\u5355\u9875\u4e2d\u663e\u793a\u7edf\u8ba1\u4fe1\u606f|\n|`page_check_metadata`|str||\u5982\u679c\u4e3a\u7a7a\uff0c\u5219\u6240\u6709\u9875\u9762\u90fd\u663e\u793a\uff1b\u5426\u5219\u5305\u542b\u6307\u5b9a metadata \u624d\u663e\u793a\u5355\u9875\u7edf\u8ba1\u4fe1\u606f|\n|`page_read_time`|bool|`True`|\u662f\u5426\u663e\u793a\u5355\u9875\u9884\u8ba1\u9605\u8bfb\u65f6\u95f4|\n|`page_template`|str||\u5355\u9875\u7edf\u8ba1\u4fe1\u606f\u6a21\u677f\u76f8\u5bf9\u8def\u5f84\uff08\u76f8\u5bf9 docs\uff09|\n|`words_per_minute`|int|`300`|\u6bcf\u5206\u949f\u9884\u8ba1\u9605\u8bfb\u5b57\u6570|\n|`codelines_per_minute`|int|`80`|\u6bcf\u5206\u949f\u9884\u8ba1\u9605\u8bfb\u4ee3\u7801\u884c\u6570|\n\n### \u51e0\u79cd\u4f7f\u7528\u65b9\u5f0f\n#### \u5168\u5c40\u7edf\u8ba1\u9875\n\u4f8b\u5982\u5728\u9996\u9875\u663e\u793a\u5168\u5c40\u7edf\u8ba1\u4fe1\u606f\u3002\u9700\u8981\u5728\u8be5\u9875\u9762\u7684\u5143\u6570\u636e\u4e2d\u6dfb\u52a0\uff1a\n```yaml\n---\nstatistics: True\n---\n```\n\u7136\u540e\u5728\u8be5\u9875\u4e2d\u9700\u8981\u7684\u90e8\u5206\u6dfb\u52a0\u5360\u4f4d\u7b26\uff0c\u4f8b\u5982\uff1a\n```markdown\n\u672c\u7ad9\u5171\u6709 {{ pages }} \u4e2a\u9875\u9762\uff0c{{ words }} \u4e2a\u5b57\uff0c{{ codes }} \u884c\u4ee3\u7801\u3002\n```\n\n#### \u5355\u9875\u7edf\u8ba1\n\u9700\u8981\u6309\u7167\u4e0a\u8ff0\u9009\u9879\u586b\u5199\u597d\u914d\u7f6e\uff08\u9ed8\u8ba4\u5f00\u542f\u5355\u9875\u7edf\u8ba1\uff0c\u4e14~~\u5e94\u8be5\u53ef\u4ee5~~\u9002\u914d material \u4e3b\u9898\uff09\u3002\n\n\u5982\u679c `page_check_metadata` \u4e3a\u7a7a\uff0c\u5219\u6240\u6709\u9875\u9762\u90fd\u663e\u793a\u5355\u9875\u7edf\u8ba1\u4fe1\u606f\uff1b\u5426\u5219\u5305\u542b\u6307\u5b9a metadata \u624d\u663e\u793a\u5355\u9875\u7edf\u8ba1\u4fe1\u606f\u3002\u4f8b\u5982\u5728\u6211\u81ea\u5df1\u7684\u8bbe\u7f6e\u4e2d\uff0c\u5305\u542b `comment` \u7684\u9875\u9762\u624d\u663e\u793a\u5355\u9875\u7edf\u8ba1\u4fe1\u606f\uff08\u4e14\u5305\u542b `nostatistics` \u7684\u9875\u9762\u4e0d\u663e\u793a\u7edf\u8ba1\u4fe1\u606f\uff09\uff1a\n```yaml\nplugins:\n - statistics:\n page_check_metadata: comment\n```\n\n### \u9ad8\u7ea7\u7528\u6cd5\n#### \u81ea\u5b9a\u4e49\u5355\u9875\u7edf\u8ba1\u6a21\u677f\n\u53ef\u4ee5\u901a\u8fc7 `page_template` \u9009\u9879\u6307\u5b9a\u5355\u9875\u7edf\u8ba1\u6a21\u677f\u7684\u76f8\u5bf9\u8def\u5f84\uff08\u76f8\u5bf9 docs\uff09\u3002\u8fd9\u4e2a\u6a21\u677f\u4f1a\u88ab\u63d2\u5165\u5230 markdown \u6e90\u7801\u7684\u4e00\u7ea7\u6807\u9898\u4e0b\u65b9\uff0c\u4f1a\u4f20\u5165 `words` `code_lines` `read_time`\uff08\u53ef\u9009\uff09\u4e09\u4e2a\u6a21\u677f\u53c2\u6570\u3002\n\n\u81ea\u5b9a\u4e49\u7684\u8bdd\u53ef\u4ee5\u53c2\u8003\u63d0\u4f9b\u7684\u6a21\u677f\u3002\n\n#### \u9605\u8bfb\u65f6\u95f4\n\u53ef\u4ee5\u901a\u8fc7 `page_read_time` \u9009\u9879\u63a7\u5236\u662f\u5426\u663e\u793a\u5355\u9875\u9884\u8ba1\u9605\u8bfb\u65f6\u95f4\u3002\u9ed8\u8ba4\u5f00\u542f\u3002\n\n\u9605\u8bfb\u65f6\u95f4\u7684\u8ba1\u7b97\u65b9\u5f0f\u662f\u5206\u522b\u8ba1\u7b97\u5b57\u6570\u548c\u4ee3\u7801\u884c\u6570\u7684\u9605\u8bfb\u65f6\u95f4\uff0c\u7136\u540e\u53d6\u4e8c\u8005\u4e4b\u548c\u3002\u53ef\u4ee5\u901a\u8fc7 `words_per_minute` \u548c `codelines_per_minute` \u9009\u9879\u5206\u522b\u8bbe\u7f6e\u6bcf\u5206\u949f\u9884\u8ba1\u9605\u8bfb\u5b57\u6570\u548c\u4ee3\u7801\u884c\u6570\u3002\u9ed8\u8ba4\u60c5\u51b5\u4e0b\u5206\u522b\u4e3a 300 \u548c 80\uff0c\u5bf9\u4e8e\u6280\u672f\u7c7b\u6587\u7ae0\u8fd9\u6837\u7684\u8bbe\u7f6e\u57fa\u672c\u5408\u7406\uff0c\u5bf9\u4e8e\u5176\u4ed6\u7c7b\u578b\u4f8b\u5982\u6587\u5b66\u7c7b\u6587\u7ae0\u6bcf\u5206\u949f\u9605\u8bfb\u5b57\u6570\u5e94\u8be5\u63d0\u9ad8\u5230 400~600 \u5de6\u53f3\u8f83\u4e3a\u5408\u7406\u3002\n\n~~\u8ba1\u5212\u6dfb\u52a0\u9875\u9762\u5143\u4fe1\u606f\u9009\u9879\u6765\u4e3a\u5355\u9875\u8bbe\u7f6e\u7279\u5b9a\u7684\u9605\u8bfb\u65f6\u95f4\u3002\uff08\u5495\u5495\u5495\uff09~~\n\n#### \u5b57\u6570\u7edf\u8ba1\u7ec6\u8282\n\u672c\u63d2\u4ef6\u7684\u5b57\u6570\u7edf\u8ba1\u7ec6\u8282\u4e3a\uff1a\u4e00\u4e2a\u82f1\u6587\u5355\u8bcd\uff08\u5305\u62ec\u6570\u5b57\uff09\u7b97\u4e00\u4e2a\u5b57\uff0c\u4e00\u4e2a\u4e2d\u6587\u6c49\u5b57\u7b97\u4e00\u4e2a\u5b57\uff0c\u6807\u70b9\u90fd\u4e0d\u7b97\u5b57\uff1b\u4ee3\u7801\u5757\uff08\u5e26\u8bed\u8a00\u7684\u4e09\u53cd\u5f15\u53f7\u8bed\u6cd5\uff09\u4e2d\u6240\u6709\u5185\u5bb9\u90fd\u4e0d\u8ba1\u5165\u5b57\u6570\uff0c\u800c\u662f\u8ba1\u5165\u4ee3\u7801\u5757\u884c\u6570\u7edf\u8ba1\u3002\n\n\u5177\u4f53\u7ec6\u8282\u89c1 plugin.py \u4e2d\u7684 \\_clean\\_markdown \u65b9\u6cd5\u3002\n\n## \u5f00\u53d1\n\u53ef\u80fd\u5f88\u4e0d\u7a33\u5b9a\uff08\u53cd\u6b63\u81f3\u5c11\u6211\u80fd\u8dd1\u8d77\u6765\uff09\uff0c\u6709\u4efb\u4f55\u95ee\u9898\u6b22\u8fce issue \u63d0\u51fa\u3002\u540c\u65f6\u9875\u6b22\u8fce\u4efb\u4f55 PR\uff0c\u5c3d\u7ba1\u63d0\u5c31\u597d\u3002\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin that generate statistic data of a site",
"version": "0.1.2",
"split_keywords": [
"mkdocs",
"python",
"markdown",
"statistics"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2a1b77c8d7d0d1cb2523932306e5f7b307d561498b1f022f0d52e6ab94c80047",
"md5": "48e9e2dfdb5d97190c0ffb6d4f670f42",
"sha256": "50fd63b43968aaea010c1a2a7767edb68c6746a6a338d93acf38617532bc32bc"
},
"downloads": -1,
"filename": "mkdocs_statistics_plugin-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "48e9e2dfdb5d97190c0ffb6d4f670f42",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 6861,
"upload_time": "2023-02-05T15:39:12",
"upload_time_iso_8601": "2023-02-05T15:39:12.254157Z",
"url": "https://files.pythonhosted.org/packages/2a/1b/77c8d7d0d1cb2523932306e5f7b307d561498b1f022f0d52e6ab94c80047/mkdocs_statistics_plugin-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0876093726a1881802ededb66fa7e028beeb0e655a96a5f6d8789ea617c0ce5b",
"md5": "7a300dd15f911c9341bd50424a2ab8cf",
"sha256": "76c808003eb300a113ad5ff9f87a53fd23d7849fd3d0e67d957972acdafed2aa"
},
"downloads": -1,
"filename": "mkdocs-statistics-plugin-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "7a300dd15f911c9341bd50424a2ab8cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 6138,
"upload_time": "2023-02-05T15:39:14",
"upload_time_iso_8601": "2023-02-05T15:39:14.315509Z",
"url": "https://files.pythonhosted.org/packages/08/76/093726a1881802ededb66fa7e028beeb0e655a96a5f6d8789ea617c0ce5b/mkdocs-statistics-plugin-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-05 15:39:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "TonyCrane",
"github_project": "mkdocs-statistics-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-statistics-plugin"
}
JSON
