# mkdocs-changelog-plugin
一个用于在 mkdocs 文档中插入 changelog 时间轴的插件。
预览：https://note.tonycrane.cc/changelog/
## 安装
可以通过 pypi 直接安装：
```shell
$ pip install mkdocs-changelog-plugin
```
也可以从源码安装
```shell
$ git clone https://github.com/TonyCrane/mkdocs-changelog-plugin.git
$ cd mkdocs-changelog-plugin
$ pip install . # or pip install -e .
```
## 使用
- 在 mkdocs.yml 中启用插件：
```yaml
plugins:
- changelog
```
- changelog 从外部的 yaml 文件读取，默认在 docs/changelog.yml 中，可以通过 file 选项来选择其他位置：
```yaml
plugins:
- changelog:
file: changelog.yml
```
- 按照格式编写 changelog yaml 文件（见下）
- 在需要插入 changelog 的页面 meta 部分中添加：
```yaml
changelog: True
```
- 在页面需要插入对应部分的位置添加：
```markdown
{{ placeholder }}
```
### changelog.yml 格式
例如：
```yaml
- "placeholder1":
- "time1":
- "type": text
- "type": text
- "placeholder":
- "time2":
- "type":
text: text
href: /link/to/page/
- "type":
text: text
href: /link/to/page/
- "time3":
- "type": text
```
- placeholder 是在 md 文件插入位置写入 {{ }} 的内容
- time 是时间标题
- type 是更改类型
- 插件内自带三种：
- newpage：新建页面
- pageupdate：页面更新
- function：功能性更新
- 可以自定义
- 插入 custom css 即可，例如自定义 refactor type：
```css
.changelog-type-refactor {
background-color: #c63f94b0;
}
.changelog-type-refactor::before {
content: "文档重构";
}
```
- 如果没有对应 css，则显示为蓝色的“更新”
- type 后可以直接写文本，会直接写在更新类型后面（不支持 markdown，但可以 html）
- type 后也可以按如上写 text 和 href，此时会给 text 加上 href 指定的 link（利用 a 元素）
具体可以参考[我的 changelog.yml](https://github.com/TonyCrane/note/blob/master/docs/changelog.yml)。
### 主题适配
感觉 mkdocs 主流主题只有 material 用得多了，所以没做其他主题的适配。基本上就差在几个颜色的问题上，问题不大，可以自己通过 css 来覆盖这里规定的颜色，具体看 css/timeline.css。
## 开发
嘛，基本就是我用纯 html+css 糊出来自己用的，然后为了方便写了个插件，代码也比较乱，在别人的主题里面可能会~~格式混乱、颜色爆炸~~。有想修改、改进的我非常且热烈欢迎，尽管 PR 就好（
## 参考
- [timvink/mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/)
- [unverbuggt/mkdocs-encryptcontent-plugin](https://github.com/unverbuggt/mkdocs-encryptcontent-plugin)
Raw data
{
"_id": null,
"home_page": "https://github.com/TonyCrane/mkdocs-changelog-plugin",
"name": "mkdocs-changelog-plugin",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": "",
"keywords": "mkdocs python markdown changelog",
"author": "TonyCrane",
"author_email": "me@tonycrane.cc",
"download_url": "https://files.pythonhosted.org/packages/ab/22/75b7cdc399ef56a524960b8f45294735d81a971ca387164c4153d5e4c4c5/mkdocs-changelog-plugin-0.1.3.tar.gz",
"platform": null,
"description": "# mkdocs-changelog-plugin\n\n\u4e00\u4e2a\u7528\u4e8e\u5728 mkdocs \u6587\u6863\u4e2d\u63d2\u5165 changelog \u65f6\u95f4\u8f74\u7684\u63d2\u4ef6\u3002\n\n\u9884\u89c8\uff1ahttps://note.tonycrane.cc/changelog/\n\n## \u5b89\u88c5\n\u53ef\u4ee5\u901a\u8fc7 pypi \u76f4\u63a5\u5b89\u88c5\uff1a\n```shell\n$ pip install mkdocs-changelog-plugin\n```\n\n\u4e5f\u53ef\u4ee5\u4ece\u6e90\u7801\u5b89\u88c5\n\n```shell\n$ git clone https://github.com/TonyCrane/mkdocs-changelog-plugin.git\n$ cd mkdocs-changelog-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 - changelog\n ```\n- changelog \u4ece\u5916\u90e8\u7684 yaml \u6587\u4ef6\u8bfb\u53d6\uff0c\u9ed8\u8ba4\u5728 docs/changelog.yml \u4e2d\uff0c\u53ef\u4ee5\u901a\u8fc7 file \u9009\u9879\u6765\u9009\u62e9\u5176\u4ed6\u4f4d\u7f6e\uff1a\n ```yaml\n plugins:\n - changelog:\n file: changelog.yml\n ```\n- \u6309\u7167\u683c\u5f0f\u7f16\u5199 changelog yaml \u6587\u4ef6\uff08\u89c1\u4e0b\uff09\n- \u5728\u9700\u8981\u63d2\u5165 changelog \u7684\u9875\u9762 meta \u90e8\u5206\u4e2d\u6dfb\u52a0\uff1a\n ```yaml\n changelog: True\n ```\n- \u5728\u9875\u9762\u9700\u8981\u63d2\u5165\u5bf9\u5e94\u90e8\u5206\u7684\u4f4d\u7f6e\u6dfb\u52a0\uff1a\n ```markdown\n {{ placeholder }}\n ```\n\n### changelog.yml \u683c\u5f0f\n\u4f8b\u5982\uff1a\n```yaml\n- \"placeholder1\":\n - \"time1\":\n - \"type\": text\n - \"type\": text\n- \"placeholder\":\n - \"time2\":\n - \"type\":\n text: text\n href: /link/to/page/\n - \"type\":\n text: text\n href: /link/to/page/\n - \"time3\":\n - \"type\": text\n```\n\n- placeholder \u662f\u5728 md \u6587\u4ef6\u63d2\u5165\u4f4d\u7f6e\u5199\u5165 {{ }} \u7684\u5185\u5bb9\n- time \u662f\u65f6\u95f4\u6807\u9898\n- type \u662f\u66f4\u6539\u7c7b\u578b\n - \u63d2\u4ef6\u5185\u81ea\u5e26\u4e09\u79cd\uff1a\n - newpage\uff1a\u65b0\u5efa\u9875\u9762\n - pageupdate\uff1a\u9875\u9762\u66f4\u65b0\n - function\uff1a\u529f\u80fd\u6027\u66f4\u65b0\n - \u53ef\u4ee5\u81ea\u5b9a\u4e49\n - \u63d2\u5165 custom css \u5373\u53ef\uff0c\u4f8b\u5982\u81ea\u5b9a\u4e49 refactor type\uff1a\n ```css\n .changelog-type-refactor {\n background-color: #c63f94b0;\n }\n .changelog-type-refactor::before {\n content: \"\u6587\u6863\u91cd\u6784\";\n }\n ```\n - \u5982\u679c\u6ca1\u6709\u5bf9\u5e94 css\uff0c\u5219\u663e\u793a\u4e3a\u84dd\u8272\u7684\u201c\u66f4\u65b0\u201d\n- type \u540e\u53ef\u4ee5\u76f4\u63a5\u5199\u6587\u672c\uff0c\u4f1a\u76f4\u63a5\u5199\u5728\u66f4\u65b0\u7c7b\u578b\u540e\u9762\uff08\u4e0d\u652f\u6301 markdown\uff0c\u4f46\u53ef\u4ee5 html\uff09\n- type \u540e\u4e5f\u53ef\u4ee5\u6309\u5982\u4e0a\u5199 text \u548c href\uff0c\u6b64\u65f6\u4f1a\u7ed9 text \u52a0\u4e0a href \u6307\u5b9a\u7684 link\uff08\u5229\u7528 a \u5143\u7d20\uff09\n\n\u5177\u4f53\u53ef\u4ee5\u53c2\u8003[\u6211\u7684 changelog.yml](https://github.com/TonyCrane/note/blob/master/docs/changelog.yml)\u3002\n\n### \u4e3b\u9898\u9002\u914d\n\u611f\u89c9 mkdocs \u4e3b\u6d41\u4e3b\u9898\u53ea\u6709 material \u7528\u5f97\u591a\u4e86\uff0c\u6240\u4ee5\u6ca1\u505a\u5176\u4ed6\u4e3b\u9898\u7684\u9002\u914d\u3002\u57fa\u672c\u4e0a\u5c31\u5dee\u5728\u51e0\u4e2a\u989c\u8272\u7684\u95ee\u9898\u4e0a\uff0c\u95ee\u9898\u4e0d\u5927\uff0c\u53ef\u4ee5\u81ea\u5df1\u901a\u8fc7 css \u6765\u8986\u76d6\u8fd9\u91cc\u89c4\u5b9a\u7684\u989c\u8272\uff0c\u5177\u4f53\u770b css/timeline.css\u3002\n\n## \u5f00\u53d1\n\u561b\uff0c\u57fa\u672c\u5c31\u662f\u6211\u7528\u7eaf html+css \u7cca\u51fa\u6765\u81ea\u5df1\u7528\u7684\uff0c\u7136\u540e\u4e3a\u4e86\u65b9\u4fbf\u5199\u4e86\u4e2a\u63d2\u4ef6\uff0c\u4ee3\u7801\u4e5f\u6bd4\u8f83\u4e71\uff0c\u5728\u522b\u4eba\u7684\u4e3b\u9898\u91cc\u9762\u53ef\u80fd\u4f1a~~\u683c\u5f0f\u6df7\u4e71\u3001\u989c\u8272\u7206\u70b8~~\u3002\u6709\u60f3\u4fee\u6539\u3001\u6539\u8fdb\u7684\u6211\u975e\u5e38\u4e14\u70ed\u70c8\u6b22\u8fce\uff0c\u5c3d\u7ba1 PR \u5c31\u597d\uff08\n\n## \u53c2\u8003\n- [timvink/mkdocs-git-revision-date-localized-plugin](https://github.com/timvink/mkdocs-git-revision-date-localized-plugin/)\n- [unverbuggt/mkdocs-encryptcontent-plugin](https://github.com/unverbuggt/mkdocs-encryptcontent-plugin)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin that create changelog in a page",
"version": "0.1.3",
"split_keywords": [
"mkdocs",
"python",
"markdown",
"changelog"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "356e0e23cc8b03f91987c607f7ed8e30a449be42aa2b011b9a0187441b31de0a",
"md5": "deb891c1ab81223e8100ba3402ad3b32",
"sha256": "24044b42752b1ca29c69ce40965ed93772800e447ede2acb39305ef7138ecfce"
},
"downloads": -1,
"filename": "mkdocs_changelog_plugin-0.1.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "deb891c1ab81223e8100ba3402ad3b32",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 6893,
"upload_time": "2023-02-05T15:46:53",
"upload_time_iso_8601": "2023-02-05T15:46:53.697808Z",
"url": "https://files.pythonhosted.org/packages/35/6e/0e23cc8b03f91987c607f7ed8e30a449be42aa2b011b9a0187441b31de0a/mkdocs_changelog_plugin-0.1.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ab2275b7cdc399ef56a524960b8f45294735d81a971ca387164c4153d5e4c4c5",
"md5": "60456c15557b2a72458661694bff2b30",
"sha256": "a4a29e09eee9ba6529ebc92ed5423a50dd41f469ccce9bca939229a7e048063f"
},
"downloads": -1,
"filename": "mkdocs-changelog-plugin-0.1.3.tar.gz",
"has_sig": false,
"md5_digest": "60456c15557b2a72458661694bff2b30",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 6024,
"upload_time": "2023-02-05T15:46:55",
"upload_time_iso_8601": "2023-02-05T15:46:55.471246Z",
"url": "https://files.pythonhosted.org/packages/ab/22/75b7cdc399ef56a524960b8f45294735d81a971ca387164c4153d5e4c4c5/mkdocs-changelog-plugin-0.1.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-05 15:46:55",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "TonyCrane",
"github_project": "mkdocs-changelog-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-changelog-plugin"
}
JSON
