构建细节

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

md文档构建

除了基本的md文本内容,docsite还支持titlekeywordsdescription三个元数据。

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

  1. ---
  2. title: demo title
  3. keywords: keywords1,keywords2,keywords3
  4. description: some description
  5. ---
  6. ## 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.jsxindex.scss文件作构建,在build目录生成对应的js和css文件,文件名为文件夹的名称。比如某个页面为pages/custom/index.jsxpages/custom/index.scss,那么会在build目录中生成custom.jscustom.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-cnen-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.htmlen-us/demo/index.html