tonycrane / mkdocs-changelog-plugin

A MkDocs plugin that create changelog in a page

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 就好（

参考

• timvink/mkdocs-git-revision-date-localized-plugin
• unverbuggt/mkdocs-encryptcontent-plugin

mkdocs-changelog-plugin's Issues

在深色/浅色模式切换时，插件似乎不能适配

我注意到css的background设置时是用了导航栏的颜色，我想要自定义，于是我覆盖原有css，但是为了支持深色/浅色模式，我写了如下css：

@media(prefers-color-scheme: light) {
    .timeline-content::before {
        content: "";
        position: absolute;
        width: 20px;
        height: 20px;
        transform: rotate(45deg);
        background-color: #aaaaaa;
        left: -10px;
        top: calc(50% - 10px);
        box-shadow: var(--md-shadow-z2);
    }
    .timeline-card {
        position: relative;
        display: -ms-flexbox;
        display: flex;
        -ms-flex-direction: column;
        flex-direction: column;
        min-width: 0;
        word-wrap: break-word;
        background-image: linear-gradient(to top, #cfd9df 0%, #e2ebf0 100%);
        /* background-image: linear-gradient(to top, #d5d4d0 0%, #d5d4d0 1%, #eeeeec 31%, #efeeec 75%, #e9e9e7 100%); */
        border-radius: .25rem;
        padding-top: 10px;
        padding-bottom: 10px;
        padding-left: 15px;
        padding-right: 10px;
        box-shadow: var(--md-shadow-z2);
    }
}

但这样并没有覆盖原有的css样式，不知道有没有什么好的办法可以做到适配深色/浅色模式的切换？

【BUG】当 docs 文件夹里面有名为 CSS（不区分大小写）的文件夹时，会让插件的样式完全丢失

我本想做一个教学网站，在 docs 文件夹下建立了一个 CSS 文件夹，专门用来放和 CSS 相关的教学内容，然后发现 ChangeLog 的样式不见了。本地预览是没有任何问题的，因为本地预览时，会区分文件夹的大小写问题，浏览器可以正常访问 css/timeline.css 文件。但是当我通过 git 上传到 GitHub 之后，gh-pages 中 ChangeLog 却怎么也显示不出来样式。

经过我两个小时的排查（我是新手，很菜），发现 git 不会区分文件夹的大小写，导致上传到 GitHub 时，我自己建立的 CSS 文件夹把 changelog 插件生成的 css 文件夹给覆盖了，导致无法显示出样式。

希望能尽快将这个问题解决！

Module not found

MacOS 13.2.1
python venv
Python 3.9.6
mkdocs-material 9.1.0
mkdocs-changelog-plugin 0.1.3

收到了下面的报错
mkdocs serve ─╯
Traceback (most recent call last):
File "/Users//Desktop/web_env/bin/mkdocs", line 8, in
sys.exit(cli())
File "/Users//Desktop/web_env/lib/python3.9/site-packages/click/core.py", line 1130, in call
return self.main(*args, **kwargs)
File "/Users//Desktop/web_env/lib/python3.9/site-packages/click/core.py", line 1055, in main
rv = self.invoke(ctx)
File "/Users//Desktop/web_env/lib/python3.9/site-packages/click/core.py", line 1657, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/Users//Desktop/web_env/lib/python3.9/site-packages/click/core.py", line 1404, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/Users//Desktop/web_env/lib/python3.9/site-packages/click/core.py", line 760, in invoke
return __callback(*args, **kwargs)
File "/Users//Desktop/web_env/lib/python3.9/site-packages/mkdocs/main.py", line 234, in serve_command
serve.serve(dev_addr=dev_addr, livereload=livereload, watch=watch, **kwargs)
File "/Users//Desktop/web_env/lib/python3.9/site-packages/mkdocs/commands/serve.py", line 78, in serve
config = get_config()
File "/Users//Desktop/web_env/lib/python3.9/site-packages/mkdocs/config/base.py", line 363, in load_config
errors, warnings = cfg.validate()
File "/Users//Desktop/web_env/lib/python3.9/site-packages/mkdocs/config/base.py", line 228, in validate
run_failed, run_warnings = self._validate()
File "/Users//Desktop/web_env/lib/python3.9/site-packages/mkdocs/config/base.py", line 186, in _validate
self[key] = config_option.validate(value)
File "/Users//Desktop/web_env/lib/python3.9/site-packages/mkdocs/config/config_options.py", line 147, in validate
return self.run_validation(value)
File "/Users//Desktop/web_env/lib/python3.9/site-packages/mkdocs/config/config_options.py", line 939, in run_validation
self.load_plugin_with_namespace(name, cfg)
File "/Users//Desktop/web_env/lib/python3.9/site-packages/mkdocs/config/config_options.py", line 975, in load_plugin_with_namespace
return (name, self.load_plugin(name, config))
File "/Users//Desktop/web_env/lib/python3.9/site-packages/mkdocs/config/config_options.py", line 993, in load_plugin
plugin_cls = self.installed_plugins[name].load()
File "/Users//Desktop/web_env/lib/python3.9/site-packages/importlib_metadata/init.py", line 208, in load
module = import_module(match.group('module'))
File "/Applications/Xcode.app/Contents/Developer/Library/Frameworks/Python3.framework/Versions/3.9/lib/python3.9/importlib/init.py", line 127, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
File "", line 1030, in _gcd_import
File "", line 1007, in _find_and_load
File "", line 972, in _find_and_load_unlocked
File "", line 228, in _call_with_frames_removed
File "", line 1030, in _gcd_import
File "", line 1007, in _find_and_load
File "", line 984, in _find_and_load_unlocked
ModuleNotFoundError: No module named 'mkdocs_changelog_plugin'

请问该如何解决呢