# 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 里提醒我，十分感谢！
Raw data
{
"_id": null,
"home_page": "https://github.com/NoughtQ/mkdocs-random_walk-plugin",
"name": "mkdocs-random-walk-plugin",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.5",
"maintainer_email": null,
"keywords": "mkdocs python markdown notes random random_walk",
"author": "NoughtQ",
"author_email": "noughtq666@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/81/c7/d55150237a231931c735749c00fff8d83e6520f276d015a80286ba047bd9/mkdocs_random_walk_plugin-0.1.1.tar.gz",
"platform": null,
"description": "# mkdocs-random_walk-plugin\r\n\r\n\u4e00\u4e2a\u7528\u4e8e mkdocs \u6587\u6863\u6f2b\u6e38\u7684\u63d2\u4ef6\uff0c\u7c7b\u4f3c Obsidian \u81ea\u5e26\u7684\u7b14\u8bb0\u6f2b\u6e38\u529f\u80fd\u7684\u7b80\u964b\u5b9e\u73b0\u3002\r\n\r\n\u8fd9\u53ea\u662f\u6211\u7684\u4e00\u4e2a toy project\uff1a\u7b80\u5355\u5730\u914d\u5408 HTML + JS \u524d\u7aef\uff0c\u4ee5\u53ca Python \u540e\u7aef\uff0c\u5b9e\u73b0\u968f\u673a\u8df3\u8f6c\u7b14\u8bb0\u7684\u529f\u80fd\u3002\u6240\u4ee5\u6211\u7684\u4ee3\u7801\u5b9e\u73b0\u6bd4\u8f83\u7c97\u7cd9\uff0c\u6709\u4e9b\u5730\u65b9\u53ef\u80fd\u8fd8\u53ef\u4ee5\u5199\u7684\u66f4\u597d\uff0c\u4f46\u9274\u4e8e\u672c\u4eba\u7684\u4ee3\u7801\u6c34\u5e73\uff0c\u76ee\u524d\u5c31\u5148\u8fd9\u6837\u5427...\r\n\r\n\u5176\u4e2d Python \u90e8\u5206\u662f\u6839\u636e [@TonyCrane](https://github.com/TonyCrane) \u524d\u8f88\u7684 [mkdocs-statistics-plugin](https://github.com/TonyCrane/mkdocs-statistics-plugin) \u4fee\u6539\u800c\u6765\u7684\uff0c\u6240\u4ee5\u4ee3\u7801\u7684\u4e00\u4e9b\u90e8\u5206\u4e0e\u5176\u5341\u5206\u76f8\u4f3c\u3002\r\n\r\n\u53ef\u4ee5\u628a\u8fd9\u4e2a\u63d2\u4ef6\u5f53\u4f5c\u83b7\u53d6\u7075\u611f\u7684\u9014\u5f84 ~~\uff0c\u4e5f\u53ef\u4ee5\u5c31\u628a\u5b83\u5f53\u4e2a\u6253\u53d1\u95f2\u6687\u65f6\u95f4\u7684\u73a9\u5177\u3002~~\r\n\r\n\u9884\u89c8\uff1a<https://note.noughtq.top/>\uff08\u6211\u7684\u7b14\u8bb0\u9996\u9875\u201c\u7b14\u8bb0\u6f2b\u6e38\u201d\u94fe\u63a5\uff09\r\n\r\n\u6211\u7684\u914d\u7f6e\uff08\u76ee\u524d\u6682\u672a\u66f4\u65b0\uff09\uff1a<https://github.com/NoughtQ/notebook/blob/master/mkdocs.yml>\r\n\r\n\r\n## \u5b89\u88c5\r\n\r\n\u53ef\u4ee5\u901a\u8fc7 pypi \u76f4\u63a5\u5b89\u88c5\uff1a\r\n\r\n```sh\r\n$ pip install mkdocs-random-walk-plugin\r\n```\r\n\r\n\u4e5f\u53ef\u4ee5\u901a\u8fc7\u6e90\u7801\u5b89\u88c5\uff1a\r\n\r\n```sh\r\n$ git clone https://github.com/NoughtQ/mkdocs-random_walk-plugin.git\r\n$ cd mkdocs-random-walk-plugin\r\n$ pip install . \r\n```\r\n\r\n## \u4f7f\u7528\r\n\r\n- \u5728 mkdocs.yml \u4e2d\u542f\u7528\u63d2\u4ef6\uff1a\r\n\r\n ```yaml\r\n plugins:\r\n - random_walk\r\n ```\r\n\r\n \u914d\u7f6e\u9009\u9879\u53ca\u89e3\u91ca\uff08\u4f18\u5148\u7ea7\u4ece\u4e0a\u5230\u4e0b\u8d8a\u6765\u8d8a\u9ad8\uff09\uff1a\r\n\r\n | \u9009\u9879 | \u7c7b\u578b | \u9ed8\u8ba4\u503c | \u89e3\u91ca |\r\n |:----|:----|:----|:----|\r\n |`include_path`|`list`|`None`|\u53ea\u7edf\u8ba1\u5339\u914d\u7684\u8def\u5f84\uff08\u53ea\u5305\u542b\u5b57\u7b26\u4e32\u9879\u7684\u5217\u8868\uff09\uff0c\u8def\u5f84\u76f8\u5bf9 docs\uff0c\u4e3a\u7a7a\u5219\u4e0d\u542f\u7528\uff09|\r\n |`exclude_path`|`list`|`None`|\u4e0d\u7edf\u8ba1\u5339\u914d\u7684\u8def\u5f84\uff08\u53ea\u5305\u542b\u5b57\u7b26\u4e32\u9879\u7684\u5217\u8868\uff09\uff0c\u8def\u5f84\u76f8\u5bf9 docs\uff0c\u4e3a\u7a7a\u5219\u4e0d\u542f\u7528\uff09|\r\n |`black_list`|`list`|`None`|\u9ed1\u540d\u5355\uff08\u6bd4 `exclude_path` \u66f4\u7075\u6d3b\uff09\u53ea\u5305\u542b\u5b57\u7b26\u4e32\u9879\u7684\u5217\u8868\uff09\uff0c\u8def\u5f84\u76f8\u5bf9 docs\uff0c\u4e3a\u7a7a\u5219\u4e0d\u542f\u7528\uff09|\r\n\r\n- \u5728\u88ab\u8bbe\u7f6e\u7b14\u8bb0\u6f2b\u6e38\u529f\u80fd\u7684 Markdown \u6587\u4ef6\uff08\u9875\u9762\uff09\u4e0a\r\n - \u5148\u5728\u5143\u6570\u636e\u5904\u542f\u7528\u529f\u80fd\uff1a\r\n\r\n ```md\r\n ---\r\n random_walk: true\r\n ---\r\n ```\r\n\r\n - \u518d\u8bbe\u7f6e HTML \u94fe\u63a5\uff08\u6ce8\u610f\u4e0d\u662f Markdown \u94fe\u63a5\uff09\r\n\r\n ```html\r\n <!-- href: \u521d\u59cb/\u9ed8\u8ba4\u94fe\u63a5 -->\r\n <!-- id: \u6307\u5b9a\u4e3a randomLink\uff0c\u4e0d\u8981\u6539\u6210\u5176\u4ed6\u503c -->\r\n <!-- markdown: \u8bbe\u7f6e\u8be5\u5c5e\u6027\uff0c\u4fbf\u4e8e\u5728 <a> \u5143\u7d20\u5185\u4f7f\u7528 Markdown \u8bed\u6cd5 -->\r\n <a href=\"#\" id=\"randomLink\" markdown=\"1\"> \r\n \u7b14\u8bb0\u6f2b\u6e38\r\n </a>\r\n ```\r\n \r\n - \u5728\u7f51\u9875\u70b9\u51fb\u8be5\u94fe\u63a5\u4fbf\u53ef\u8df3\u8f6c\u5230\u8be5\u9875\u9762\u6240\u5728\u76ee\u5f55\u4e0b\u7684\u4efb\u4e00\u9875\u9762\uff0c\u5237\u65b0\u9875\u9762\u540e\u4f1a\u91cd\u65b0\u751f\u6210\u968f\u673a\u94fe\u63a5\r\n\r\n\r\n## \u95ee\u9898\r\n\r\n\u76ee\u524d\u5728\u81ea\u5df1\u7535\u8111\u4e0a\u8dd1\u6ca1\u6709\u4ec0\u4e48\u95ee\u9898\uff0c\u4f46\u6211\u4e0d\u786e\u4fdd\u5728\u5404\u4f4d\u7684\u7535\u8111\u4e0a\u80fd\u591f\u6b63\u5e38\u8fd0\u884c\uff0c\u6240\u4ee5\u5982\u679c\u53d1\u73b0 bug \u7684\u8bdd\u8bf7\u53ca\u65f6\u5728 Issues \u91cc\u63d0\u9192\u6211\uff0c\u5341\u5206\u611f\u8c22\uff01\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin that generates a random link of pages",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/NoughtQ/mkdocs-random_walk-plugin"
},
"split_keywords": [
"mkdocs",
"python",
"markdown",
"notes",
"random",
"random_walk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "92b426e7af6eb5136be4e498156541a42e7c8c98ef9d33196d9ccacaa15e05b6",
"md5": "2afba76dc93f19209815f08c8e4c4c1f",
"sha256": "06339c3431d51c871977aebb698756ab92a764e6427c215a75556c3d8ed2c53c"
},
"downloads": -1,
"filename": "mkdocs_random_walk_plugin-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2afba76dc93f19209815f08c8e4c4c1f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.5",
"size": 6350,
"upload_time": "2025-02-01T08:30:05",
"upload_time_iso_8601": "2025-02-01T08:30:05.695206Z",
"url": "https://files.pythonhosted.org/packages/92/b4/26e7af6eb5136be4e498156541a42e7c8c98ef9d33196d9ccacaa15e05b6/mkdocs_random_walk_plugin-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "81c7d55150237a231931c735749c00fff8d83e6520f276d015a80286ba047bd9",
"md5": "aee79187058a5d3c6f30757649a66514",
"sha256": "cab41380b353428881658235abb681283c96c99619f7544401cbce48d346ff5d"
},
"downloads": -1,
"filename": "mkdocs_random_walk_plugin-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "aee79187058a5d3c6f30757649a66514",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.5",
"size": 5668,
"upload_time": "2025-02-01T08:30:07",
"upload_time_iso_8601": "2025-02-01T08:30:07.759753Z",
"url": "https://files.pythonhosted.org/packages/81/c7/d55150237a231931c735749c00fff8d83e6520f276d015a80286ba047bd9/mkdocs_random_walk_plugin-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-01 08:30:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NoughtQ",
"github_project": "mkdocs-random_walk-plugin",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "mkdocs-random-walk-plugin"
}
JSON
