confluence统计用户文章_gatsby 官网：文章与 url

印象流，先猜一波

从源代码来看，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

可以看到，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 介绍规则。

长期计划：

开发图形化文件目录管理系统。