Facebook Docusaurus 中文文档 Markdown 功能

此系列文章的应用示例已发布于 GitHub: docusaurus-docs-Zh_CN. 能够 Fork 帮助改进或 Star 关注更新. 欢迎 Star.

Markdown 功能

Markdown 头部

文档

文档使用下面的 markdown 头部字段，这两个标题字段在两边用 --- 括起来：

id：一个惟一的文件 ID。 若是这个字段不存在，文档的 id 将默认为文件名（不包括扩展名）。

title：文档的标题。 若是这个字段不存在，文档的 title 将默认为 id。

sidebar_label：文档边栏中显示的文本。 若是该字段不存在，文档的 sidebar_label 将默认为其 title。

示例:

---
id: doc1
title: My Document
sidebar_label: Document
---

版本化的文档在被复制时将其 ID 更改成包含版本号。 新的 id 是 version-${version}-${id}，其中 ${version} 是该文档的版本号， ${id} 是原始的 id。 此外，版本化的文档还会得到原始文档 ID 添加成的 original_id 字段。

示例:

---
id: version-1.0.0-doc1
title: My Document
sidebar_label: Document
original_id: doc1
---

博客博文

博客博文使用如下 markdown 头部字段标记，在两边都用一行 --- 括起来：

title：这篇博文的标题。

author：这篇博文的做者。 若是该字段被省略，则不会显示做者姓名。

authorURL：网站用户点击做者姓名时要连接的页面。 若是这个字段被省略，做者的名字将不会连接到任何东西。

authorFBID：做者的 Facebook 标识，只用于获取做者的我的资料图片以显示博客文章。 若是此字段被忽略，则不会显示做者图片的博客文章。

示例:

---
title: My First Blog Post
author: Frank Li
authorURL: http://twitter.com/franchementli
authorFBID: 100002976521003
---

额外功能

在使用 Markdown 编写文档时，Docusaurus 支持一些额外的功能。

连接其余文档

你可使用相对的 URL 到其余文档文件，当它们被渲染时，它们会自动转换成相应的 html 连接。

示例:

[This links to another document](other-document.md)

这个 markdown 会自动转换成一个连接到 /docs/other-document.html （或适当的 翻译/版本）的连接。

当你想浏览 GitHub 上的文档时，这可能会有所帮助，由于连接将会连接到其余文档（仍然在 GitHub 上），可是文档在呈现时会有正确的HTML连接。

连接到图像和其余资源

静态资源能够经过使用相对 URL 连接到文档相同的方式。 文档和博客中使用的静态资源应该分别进入 docs/assets 和 website/blog/assets。 Markdown 将被转换成正确的连接路径，以便这些路径将适用于全部语言和版本的文档。

示例:

![alt-text](assets/doc-image.png)

生成目录

您能够建立自动生成的连接列表，这些连接能够用做 API 文档的目录。

在您的 markdown 文件中，插入一行为 <AUTOGENERATED_TABLE_OF_CONTENTS> 的文字。 用代码块中的每一个函数的 h3 头文件写你的文档。 这些将被 Docusaurus 找到，而且这些部分的连接列表将被插入到文本 <AUTOGENERATED_TABLE_OF_CONTENTS> 中。

示例:

### `docusaurus.function(a, b)`

Text describing my function


### `docdoc(file)`

Text describing my function

将生成目录的功能：

- `docusaurus.function(a, b)`
- `docdoc(file)`

每一个函数都会连接到页面中的相应部分。

语法高亮

隔离的代码块默认启用语法高亮显示。 会自动检测语言，但经过指定语言，您有时能够得到更好的结果。 您可使用信息字符串，在三个开启反引号以后这样作。 如下JavaScript示例...

ReactDOM.render(
  <h1>Hello, world!</h1>,
  document.getElementById('root')
);

...会像语法高亮显示同样：

ReactDOM.render(
  <h1>Hello, world!</h1>,
  document.getElementById('root')
);

高亮显示由 Highlight.js 使用 siteConfig.js 文件中指定的主题做为 highlight 键的一部分提供：

highlight: {
  theme: 'default'
}

您能够在 Highlight.js styles目录中找到支持的主题的完整列表。

注册其余语言

尽管 Highlight.js 支持许多开箱即用的语言，但您可能须要注册其余语言支持。 对于这些状况，咱们经过暴露 hljs 常量做为 highlight 配置键的一部分来提供接口。 这可让你调用 registerLanguage：

highlight: {
  theme: 'default',
  hljs: function(hljs) {
    hljs.registerLanguage('galacticbasic', function(hljs) {
      // ...
    });
  }
}

若是这篇文章对您有帮助, 感谢 下方点赞 或 Star GitHub: docusaurus-docs-Zh_CN 支持, 谢谢.