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: about 2 months 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 (about 2 years ago)
• Default Branch: master
• Last Pushed: 2023-11-22T23:30:11.000Z (about 1 year ago)
• Last Synced: 2024-04-24T02:01:02.498Z (8 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)