一个用 Markdown 维护的个人知识库，收录实用工具、优质网站和教程。
- 网站：https://study-233.github.io/useful-notes/
- 技术：MkDocs + Material for MkDocs
- 发布：提交到
main后，由 GitHub Actions 构建并发布到 GitHub Pages
需要 Python 3.12 或更新版本。在项目目录打开 PowerShell：
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m mkdocs serve --dev-addr 127.0.0.1:8765打开终端打印的网址；保存 Markdown 后，预览会自动更新。已经建立环境后，日常只需要运行最后一条命令。
macOS / Linux 对应使用 .venv/bin/python。
| 内容 | 文件 |
|---|---|
| 首页分类与快捷入口 | docs/index.md |
| 网页翻译工具 | docs/tools/translation.md |
| Zotero 插件 | docs/tools/zotero.md |
| 网站收藏 | docs/websites.md |
| 教程列表 | docs/tutorials/index.md |
| ChatGPT 订阅教程 | docs/tutorials/chatgpt-subscription.md |
| 网站名称、主题、导航 | mkdocs.yml |
| 少量自定义样式 | docs/assets/stylesheets/extra.css |
docs/ 内的内容会发布到网站。templates/ 是复制用的模板，不会出现在网站和搜索结果中。
- 打开相应分类页。
- 从
templates/resource.md复制一个资源条目，放到页面中合适的位置。 - 用
##写资源名称；如果放在已有主题下面，就用###。下面写简介、用途和完整网址，标题会自动出现在右侧文章目录中。 - 如果希望首页也能直接打开它，在
docs/index.md的对应分类下补充一条 Markdown 列表链接。
例如，在 docs/websites.md 末尾添加：
## arXiv
浏览和查找计算机科学、数学等领域的预印本论文。
[访问 arXiv](https://arxiv.org/)需要同步首页时，在对应分类下添加 - [arXiv](https://arxiv.org/)：预印本论文网站。 即可。
外部网址保留原始参数和 # 后的筛选内容。例如插件商店的 #tags=favorite 不应删除。
- 复制
templates/tutorial.md到docs/tutorials/，使用简短英文文件名，例如zotero-backup.md。 - 替换标题、简介和正文。使用
##、###标题，右侧文章目录会自动生成。 - 在
docs/tutorials/index.md的“操作教程”下，参照现有条目添加教程标题、简介和正文链接，例如[阅读全文](zotero-backup.md)。 - 在
mkdocs.yml的nav→ “教程与学习”下添加：
nav:
# 保留其他已有分类，在现有“教程与学习”下追加最后一项。
- 教程与学习:
- 学习资源: tutorials/index.md
- ChatGPT 订阅教程: tutorials/chatgpt-subscription.md
- Zotero 备份教程: tutorials/zotero-backup.md其他页面链接到这篇教程时，使用相对于当前 Markdown 文件的路径，例如首页使用 tutorials/zotero-backup.md。这样本地预览和 GitHub Pages 的仓库子路径都能正常工作。
将图片放在 docs/assets/images/。例如，在教程文章中写：
代码用三个反引号包围，并注明语言。页面会提供代码复制按钮：
```powershell
python --version
```分类导航在 mkdocs.yml 的 nav 中维护。新增分类时创建对应 Markdown 页面，再添加导航项，并同步首页的分类入口。
修改 site_name 可以调整站名；也请同步首页标题和这份说明。如果更换仓库或域名，同时更新 site_url、repo_url 和 repo_name。site_url 必须包含仓库子路径，并以 / 结尾。
提交前运行：
.\.venv\Scripts\python.exe -m mkdocs build --strict构建成功后，提交并推送：
git add docs mkdocs.yml
git commit -m "Update notes"
git push origin main首次启用时，在 GitHub 仓库 Settings → Pages → Build and deployment → Source 选择 GitHub Actions。仓库默认公开，内容提交到 main 后自动发布，也可在 Actions 页面手动运行工作流。
Pull Request 只运行构建检查，不发布。构建失败时，本次内容不会发布；在仓库 Actions 页面查看失败步骤并修复。需要恢复旧内容时，撤销对应提交再推送即可。
requirements.txt 固定构建依赖，包含用于中文搜索分词的 jieba。升级依赖后先本地构建并验证中英文搜索，再更新版本锁定文件和提交。