我该咋写这个知识库捏
这是什么
这是一个用于沉淀学习过程和知识成果的个人知识库。
博客更适合线性记录和阶段性分享;知识库更适合分类、检索和长期积累。这里的内容不要求一次写完,而是允许在学习过程中持续补充、修订和重新组织。
目录结构
| 目录 | 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。已经分享或收录的页面在改名后可能失效,因此修改前应确认是否需要保留旧链接或增加重定向。
新增或修改文档
推荐按以下流程操作:
- 根据主题选择
science/、humanities/或arts/。 - 如果是一个新的分类,创建目录和
index.md,并在概览页说明该分类的范围。 - 为文章选择清晰、稳定的文件名;需要缩短 URL 时,优先使用简短英文文件名。
- 使用一级标题作为文章标题,例如
# 外部排序。 - 图片使用相对路径引用,并确认大小写与文件名完全一致。
- 完成后先在本地预览,再执行严格构建和空白检查。
文章不必为了“看起来完整”一次堆满所有内容。优先保证标题、结论、公式、示例和引用关系清楚,后续再增补细节。
本地预览与构建
在仓库根目录执行:
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/下的编译产物。 - 修改要尽量小而明确,避免无关的批量重命名。
- 新增功能或配置后,补充相应的说明,并用实际构建结果验证。
- 对不确定的内容保留来源、推导过程或待核验说明,不把猜测写成结论。