Skip to content

TonyCrane/mkdocs-changelog-plugin

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

9 Commits
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

mkdocs-changelog-plugin

一个用于在 mkdocs 文档中插入 changelog 时间轴的插件。

预览:https://note.tonycrane.cc/changelog/

安装

可以通过 pypi 直接安装:

$ pip install mkdocs-changelog-plugin

也可以从源码安装

$ git clone https://github.com/TonyCrane/mkdocs-changelog-plugin.git
$ cd mkdocs-changelog-plugin
$ pip install . # or pip install -e .

使用

  • 在 mkdocs.yml 中启用插件:
    plugins:
        - changelog
  • changelog 从外部的 yaml 文件读取,默认在 docs/changelog.yml 中,可以通过 file 选项来选择其他位置:
    plugins:
      - changelog:
          file: changelog.yml
  • 按照格式编写 changelog yaml 文件(见下)
  • 在需要插入 changelog 的页面 meta 部分中添加:
    changelog: True
  • 在页面需要插入对应部分的位置添加:
    {{ placeholder }}

changelog.yml 格式

例如:

- "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:
        .changelog-type-refactor {
            background-color: #c63f94b0;
        }
        .changelog-type-refactor::before {
            content: "文档重构";
        }
      • 如果没有对应 css,则显示为蓝色的“更新”
  • type 后可以直接写文本,会直接写在更新类型后面(不支持 markdown,但可以 html)
  • type 后也可以按如上写 text 和 href,此时会给 text 加上 href 指定的 link(利用 a 元素)

具体可以参考我的 changelog.yml

主题适配

感觉 mkdocs 主流主题只有 material 用得多了,所以没做其他主题的适配。基本上就差在几个颜色的问题上,问题不大,可以自己通过 css 来覆盖这里规定的颜色,具体看 css/timeline.css。

开发

嘛,基本就是我用纯 html+css 糊出来自己用的,然后为了方便写了个插件,代码也比较乱,在别人的主题里面可能会格式混乱、颜色爆炸。有想修改、改进的我非常且热烈欢迎,尽管 PR 就好(

参考