构建细节

本篇简单介绍下docsite的构建细节，便于更好的理解和使用docsite。

md文档构建

除了基本的md文本内容，docsite还支持title，keywords，description三个元数据。

在本地开发时，当新增、修改、删除md文档时，会在对应目录中生成对应的json文件，比如/blog/zh-cn/demo.md文档中内容如下：

  1. ---
  2. title: demo title
  3. keywords: keywords1,keywords2,keywords3
  4. description: some description
  5. ---
  7. ## the title

则会在/zh-cn/blog/下生成一个demo.json文件，内容如下：

  1. {
  2.   "title": "title",
  3.   "keywords": "keywords1,keywords2,keywords3",
  4.   "description": "some description",
  5.   "__html": "<h2>the title</h2>",
  6.   "filename": "demo.md",
  7. }

js、css构建

docsite会对pages目录下的一级文件夹中的index.jsx和index.scss文件作构建，在build目录生成对应的js和css文件，文件名为文件夹的名称。比如某个页面为pages/custom/index.jsx，pages/custom/index.scss，那么会在build目录中生成custom.js和custom.css文件。

html构建

html构建主要生成两类页面，一个是功能性页面，一个是站点页面。

  • 功能页面
    docsite会根据redirect.ejs在根目录下生成一个index.html文件，用作访问根目录时的跳转。还会生成一个404.html，用于某些静态站点托管平台的自定义404页面的功能。当用户访问一个不存在的页面时，平台会将用户导向404.html，进而跳转到正常的页面。

  • 站点页面
    对于站点页面，docsite依据template.ejs生成HTML页面，页面中引入合适的静态资源。主要分为首页、md页和其他页面三种类型，现分别作说明：

  • 首页
    docsite将src/pages/home文件夹下的index.jsx转换为index.html文件，放置在zh-cn和en-us目录下。

  • md页
    文档页中，结合docs/zh-cn（或docs/en-us）中的md文档和src/pages/documentation，转换成对应的HTML文件。比如某个文档为docs/zh-cn/demo.md，则会生成zh-cn/docs/demo.html。

博客详情页中，结合blog/zh-cn（或blog/en-us）中的md文档和src/pages/blogDetail，转换成对应的HTML文件。比如某个博客为blog/en-us/demo.md，则会生成en-us/blog/demo.html。

  • 其他页面
    比如某个页面的jsx代码位置为src/pages/demo/index.jsx，则会生成zh-cn/demo/index.html和en-us/demo/index.html。