印象流,先猜一波
从源代码来看,gatsby 文档的目录是由 /www/src/data/sidebars 下面的几个 yaml 配置文件管理的。比如 docs-links.yaml 对应的是 https://www.gatsbyjs.org/docs/ 的 sidebar。这是一部分源码:
- title: Documentation
key: docs
breadcrumbTitle: Docs
items:
- title: Introduction
link: /docs/
- title: Quick Start
link: /docs/quick-start/
- title: Plugin Library
link: /plugins/
- title: Starter Library
link: /starters/
- title: Awesome Gatsby Resources
link: /docs/awesome-gatsby-resources/
- title: Recipes
link: /docs/recipes/
items:
- title: Pages and Layouts
link: /docs/recipes/pages-layouts/
- title: Styling with CSS
link: /docs/recipes/styling-css/
- title: Working with Plugins
link: /docs/recipes/working-with-plugins/
- title: Working with Starters
link: /docs/recipes/working-with-starters/
- title: Working with Themes
link: /docs/recipes/working-with-themes/
- title: Sourcing Data
link: /docs/recipes/sourcing-data/
- title: Querying Data
link: /docs/recipes/querying-data/
- title: Working with Images
link: /docs/recipes/working-with-images/
- title: Transforming Data
link: /docs/recipes/transforming-data/
- title: Deploying Your Site
link: /docs/recipes/deploying-your-site/
对应的 sidebar
![8d4d40b96e6762823f5ecf1e965a42d5.png](https://i-blog.csdnimg.cn/blog_migrate/f3736a967c28fe20b700783c86572aac.png)
可以看到,yaml 文件定义了 sidebar 的层级结构,每一项的名称,url 路径,还有顺序。
接下来再看看每一个路径和具体文章的对应规则。找到源码 /docs/docs/index.md,对照内容,发现对应的 url 路径是 /docs。可以推测,从文章的 /docs 的根目录开始,docs 目录对应 url 路径的规则:
文章路径 /docs/{path}/*.md
url 路径 /{path}/*
如果 *.md 是 index.md, 则 url 路径编程 /{path}。
小心求证
找到文件 /www/src/utils/docs.js,这个文件是用来生成 docs 页面,里面有这样一个函数:
const docSlugFromPath = parsedFilePath => {
if (parsedFilePath.name !== `index` && parsedFilePath.dir !== ``) {
return `/${parsedFilePath.dir}/${parsedFilePath.name}/`
} else if (parsedFilePath.dir === ``) {
return `/${parsedFilePath.name}/`
} else {
return `/${parsedFilePath.dir}/`
}
}
这里的逻辑印证了上面对文章和url映射逻辑的猜测,可以看到,如果文件名是 index,对应的 url 路径就是文章目录(最后一个 else)。如果目录名为空,我猜测应该是指 /docs 根目录下的 md 文件,则用文件名作为 url 路径。
回头查找了 /docs 目录下的文件,只找到除 README.md 之外唯一的 md 文件:accessibility-statement.md,官网上确实有对应的路径,https://www.gatsbyjs.org/accessibility-statement/,映射规则符合刚才的推测。
这个 docs.js 经过层层调用,最后使用 createPage API 创建页面。这部分通过调用关系很容易搞清楚,就不展开了。
为什么我要研究这个?
公司决定决定使用 gatsby 管理文档,取代之前的 confluence。
https://www.atlassian.com/software/confluence
目前比较尖锐的问题有两个,一个是如何管理文档结构,第二个是各种 diagram 的支持。我的主要精力现在第一个问题上。这个项目相对于以往的项目最大的区别是,用户必须熟悉一些相对偏技术的规则才能正常使用。比如,产品经理会频繁的更新和添加 markdown 文档。当新文档被添加,或者老文档的目录结构要调整,就必须按照上面介绍的规则,更新对应的 yaml 文件。这个操作相对于 confluence 的图形化操作来说,相对抽象,也更容易出错。
了解规则只是第一步。接下来做什么,还没想好。按照我的习惯,短期计划和长期计划至少都得有一个。
短期计划:
准备文档和 demo 介绍规则。
长期计划:
开发图形化文件目录管理系统。