简介

稀土教程是由稀土掘金社区开源共建的面向职业开发者的学习资料。

如果你是来学习的，点开左侧菜单，选择你想学习的课程，就可以愉快地开启你的学习之旅！

如果你想加入到课程内容贡献者的行列，那你可以仔细往下阅读这篇文章。

创建文档

稀土教程基于Docz构建，并且在Github开源。你可以在GitHub仓库中添加内容，具体的方式是直接在src/docs目录下任意子目录中添加mdx文件。

MDX是Markdown语法扩展，你可以使用所有标准的Markdown语法，且能够引入React Components，你甚至可以根据实际需要，开发自己的组件。

只要你在添加的MDX文件的开头添加name、route、menu以及可选的submenu配置：

---
name: 文件名
route: /路径
menu: 目录
submenu: 二级目录
---

就可以在教程的左侧菜单中显示出来。

管理目录

Docz 支持配置目录顺序，你可以编辑src/docs下的menurc.js文件修改目录配置，这个文件的内容大致如下：

const JavaScript = require('./javascript/menurc');
const HTML = require('./html/menurc');
const CSS = require('./css/menurc');

module.exports = [
  HTML,
  CSS,
  JavaScript,
];

你可以添加或修改src/docs对应的子目录中的menurc.js文件，并将它引入到src/docs/menurc.js，比如src/docs/js下的文件内容如下：

module.exports = { 
  name: 'JavaScript', 
  menu: [
    '概览',
    // JS基础
    '基本语法和类型',
    '新类型：BigInt',
    ...
    // JS进阶
    '概览-进阶',
    ...
    // JS高级
    '概览-高级',
    ...
    // 运行环境 runtime
    '浏览器中的JS',
  ] 
};

如果不修改，默认会按照字符串顺序排列目录。

Components

MDX支持非常灵活的组件扩展能力，你可以在src/components目录下添加自定义组件，比如目前已有的码上掘金组件。

Docz默认提供了Playground组件，它可以嵌入其他组件代码并支持实时编辑和运行，例如下面的代码演示了码上掘金组件，你可以更换codeId来替换不同的码上掘金代码块。

<JCode codeId="7101205186751758367"></JCode>

我默认扩展了一些常用组件，比如顶部菜单：

<TopMenu
  code="//code.juejin.cn"
  pins="//juejin.cn/pins/club/6824710202655244301"
  docs="//juejin.cn"
/>

Tabs:

<Tabs activeId="1">
  <Tabs.Tab id="1" title="Tab 1">
    Tab content 1
  </Tabs.Tab>
  <Tabs.Tab id="2" title="Tab 2">
    Tab content 2
  </Tabs.Tab>
  <Tabs.Tab id="3" title={<i>Tab 3</i>}>
    Tab content 3
  </Tabs.Tab>
</Tabs>

还可以基于mermaid绘制流程图：

<Diagram theme="dark">{`
  graph TD
  Start --> Stop
`}</Diagram>

基于KaTeX书写公式：

<KaTeX macros={{ '\\f': '#1f(#2)' }}>{String.raw`
% \f is defined as #1f(#2) using the macro
\f\relax{x} = \int_{-\infty}^\infty
    \f\hat\xi\,e^{2 \pi i \xi x}
    \,d\xi
`}</KaTeX>

本地调试

将Github仓库代码Clone到本地，安装依赖：npm install，然后运行npm start即可运行。

注意 🐶，因为需要一些MDX插件来正确解析MD语法，但是docz的bug未修复，在第一次运行npm start的时候，项目会自动将根目录下的gatsby-config.fix.js内容替换到node_modules/gatsby-theme-docz/gatsby-config.js中。

可能是因为docz的Gatsby版本较老，第一次访问develop环境localhost:3000会有点慢，页面刷出来之后就可以热更新了。build后部署的版本没有这个问题。

生成和部署

运行npm run docz:build，将目录.docz/dist下的文件部署到服务器即可。

如果要更新github.io的服务，运行npm run deploy然后提交PR到Github仓库，merge后网站内容就会更新。