Metadata-Version: 2.2
Name: mkdocs-random_walk-plugin
Version: 0.1.1
Summary: A MkDocs plugin that generates a random link of pages
Home-page: https://github.com/NoughtQ/mkdocs-random_walk-plugin
Author: NoughtQ
Author-email: noughtq666@gmail.com
License: MIT
Keywords: mkdocs python markdown notes random random_walk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.5
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mkdocs
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# mkdocs-random_walk-plugin

一个用于 mkdocs 文档漫游的插件，类似 Obsidian 自带的笔记漫游功能的简陋实现。

这只是我的一个 toy project：简单地配合 HTML + JS 前端，以及 Python 后端，实现随机跳转笔记的功能。所以我的代码实现比较粗糙，有些地方可能还可以写的更好，但鉴于本人的代码水平，目前就先这样吧...

其中 Python 部分是根据 [@TonyCrane](https://github.com/TonyCrane) 前辈的 [mkdocs-statistics-plugin](https://github.com/TonyCrane/mkdocs-statistics-plugin) 修改而来的，所以代码的一些部分与其十分相似。

可以把这个插件当作获取灵感的途径 ~~，也可以就把它当个打发闲暇时间的玩具。~~

预览：<https://note.noughtq.top/>（我的笔记首页“笔记漫游”链接）

我的配置（目前暂未更新）：<https://github.com/NoughtQ/notebook/blob/master/mkdocs.yml>


## 安装

可以通过 pypi 直接安装：

```sh
$ pip install mkdocs-random-walk-plugin
```

也可以通过源码安装：

```sh
$ git clone https://github.com/NoughtQ/mkdocs-random_walk-plugin.git
$ cd mkdocs-random-walk-plugin
$ pip install . 
```

## 使用

- 在 mkdocs.yml 中启用插件：

    ```yaml
    plugins:
      - random_walk
    ```

    配置选项及解释（优先级从上到下越来越高）：

    | 选项 | 类型 | 默认值 | 解释 |
    |:----|:----|:----|:----|
    |`include_path`|`list`|`None`|只统计匹配的路径（只包含字符串项的列表），路径相对 docs，为空则不启用）|
    |`exclude_path`|`list`|`None`|不统计匹配的路径（只包含字符串项的列表），路径相对 docs，为空则不启用）|
    |`black_list`|`list`|`None`|黑名单（比 `exclude_path` 更灵活）只包含字符串项的列表），路径相对 docs，为空则不启用）|

- 在被设置笔记漫游功能的 Markdown 文件（页面）上
  - 先在元数据处启用功能：

    ```md
    ---
    random_walk: true
    ---
    ```

  - 再设置 HTML 链接（注意不是 Markdown 链接）

    ```html
    <!-- href: 初始/默认链接 -->
    <!-- id: 指定为 randomLink，不要改成其他值 -->
    <!-- markdown: 设置该属性，便于在 <a> 元素内使用 Markdown 语法 -->
    <a href="#" id="randomLink" markdown="1">  
      笔记漫游
    </a>
    ```
  
  - 在网页点击该链接便可跳转到该页面所在目录下的任一页面，刷新页面后会重新生成随机链接


## 问题

目前在自己电脑上跑没有什么问题，但我不确保在各位的电脑上能够正常运行，所以如果发现 bug 的话请及时在 Issues 里提醒我，十分感谢！
