跳转至

我该咋写这个知识库捏

这是什么

这是一个用于沉淀学习过程和知识成果的个人知识库。

博客更适合线性记录和阶段性分享;知识库更适合分类、检索和长期积累。这里的内容不要求一次写完,而是允许在学习过程中持续补充、修订和重新组织。

目录结构

目录 URL 内容
自然与应用科学 /science/ 数学、计算机、密码学、人工智能等
人文与社会科学 /humanities/ 宗教、语言、社会和人文相关内容
艺术与文化生活 /arts/ 艺术、生活经验和兴趣记录
关于知识库 /about/ 本手册、Markdown 规范和编译排错指南

about/ 是辅助说明目录,不会出现在首页的知识分类树中。可以通过页面底部的“关于知识库”链接进入,也可以直接访问 /about/。

文件与 URL 规则

  • docs/ 是文档源目录,MkDocs 会根据其中的 Markdown 文件生成网站。
  • 每个分类目录的 index.md 是该目录的概览页。
  • 一级目录使用简短英文名称,以避免 URL 过长;页面标题和正文仍然可以使用中文。
  • 子目录和文章文件名目前以内容可读性为优先,可以使用中文。
  • docs/science/example.md 会生成 /science/example/。
  • docs/science/topic/index.md 会生成 /science/topic/。
  • 图片、脚本和样式等静态资源应放在对应目录的 assets/ 中,避免与文章混放。

修改文件名或目录名会改变页面 URL。已经分享或收录的页面在改名后可能失效,因此修改前应确认是否需要保留旧链接或增加重定向。

新增或修改文档

推荐按以下流程操作:

  1. 根据主题选择 science/、humanities/ 或 arts/。
  2. 如果是一个新的分类,创建目录和 index.md,并在概览页说明该分类的范围。
  3. 为文章选择清晰、稳定的文件名;需要缩短 URL 时,优先使用简短英文文件名。
  4. 使用一级标题作为文章标题,例如 # 外部排序。
  5. 图片使用相对路径引用,并确认大小写与文件名完全一致。
  6. 完成后先在本地预览,再执行严格构建和空白检查。

文章不必为了“看起来完整”一次堆满所有内容。优先保证标题、结论、公式、示例和引用关系清楚,后续再增补细节。

本地预览与构建

在仓库根目录执行:

mkdocs serve

然后打开终端输出的本地地址。修改 Markdown 后,浏览器会自动刷新;涉及目录、URL 或主题配置的修改时,应重新检查实际链接。

提交前执行:

mkdocs build --strict --clean
git diff --check

其中:

  • mkdocs build --strict --clean 从干净的 site/ 目录构建整站,并将警告视为错误。
  • git diff --check 检查行尾空格、空白错误和冲突标记。
  • 新增但尚未被 Git 跟踪的文件不会被 git diff --check 检查,应额外确认文件本身没有行尾空格。

构建通过后,还应抽查本次修改涉及的页面,重点查看公式、嵌套列表、表格、代码块和图片。

发布前检查

发布前至少确认:

  • 页面标题和目录层级正确。
  • 内部链接可以打开,没有指向旧中文一级目录的链接。
  • 图片和附件在本地构建结果中正常显示。
  • 公式没有显示为裸 $、$$ 或普通代码。
  • 列表没有粘连、跳号或错误缩进。
  • 首页目录树只显示知识分类,站点说明从页脚进入。
  • 生成的页面 URL 与预期一致。

如果只修改了 Markdown 内容,通常不需要调整 mkdocs.yml。如果修改了主题、插件、hook 或静态资源,应进行一次完整严格构建。

相关文档

维护原则

  • 内容优先于装饰,先保证知识准确、结构清楚,再调整样式。
  • 源 Markdown 是唯一应直接修改的内容,不要手动编辑 site/ 下的编译产物。
  • 修改要尽量小而明确,避免无关的批量重命名。
  • 新增功能或配置后,补充相应的说明,并用实际构建结果验证。
  • 对不确定的内容保留来源、推导过程或待核验说明,不把猜测写成结论。