Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/TonyCrane/mkdocs-changelog-plugin
A MkDocs plugin that create changelog in a page
https://github.com/TonyCrane/mkdocs-changelog-plugin
changelog mkdocs mkdocs-material mkdocs-plugin
Last synced: 7 days ago
JSON representation
A MkDocs plugin that create changelog in a page
- Host: GitHub
- URL: https://github.com/TonyCrane/mkdocs-changelog-plugin
- Owner: TonyCrane
- License: mit
- Created: 2022-11-30T13:29:35.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2023-11-22T23:30:11.000Z (12 months ago)
- Last Synced: 2024-04-24T02:01:02.498Z (7 months ago)
- Topics: changelog, mkdocs, mkdocs-material, mkdocs-plugin
- Language: Python
- Homepage:
- Size: 19.5 KB
- Stars: 17
- Watchers: 2
- Forks: 2
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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)