# Markdown 功能

## Markdown 头部

### 文档

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

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

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

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

示例:

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

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

示例:

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

### 博客博文

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

`title`：这篇博文的标题。

`author`：这篇博文的作者。 如果该字段被省略，则不会显示作者姓名。

`authorURL`：网站用户点击作者姓名时要链接的页面。 如果这个字段被省略，作者的名字将不会链接到任何东西。

`authorFBID`：作者的 Facebook 标识，只用于获取作者的个人资料图片以显示博客文章。 如果此字段被忽略，则不会显示作者图片的博客文章。

示例:

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

## 额外功能

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

### 链接其他文档

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

示例:

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

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

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

### 链接到图像和其他资源

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

示例:

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

### 生成目录

您可以创建自动生成的链接列表，这些链接可以用作 API 文档的目录。

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

示例:

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

Text describing my function


### `docdoc(file)`

Text describing my function
```

将生成目录的功能：

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

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

## 语法高亮

隔离的代码块默认启用语法高亮显示。 会自动检测语言，但通过指定语言，您有时可以获得更好的结果。 您可以使用[信息字符串](https://github.github.com/gfm/#example-111)，在三个开启反引号之后这样做。 以下JavaScript示例...

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

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

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

高亮显示由 [Highlight.js](https://highlightjs.org) 使用 `siteConfig.js` 文件中指定的主题作为 `highlight` 键的一部分提供：

```javascript
highlight: {
  theme: 'default'
}
```

您可以在 Highlight.js [`styles`](https://github.com/isagalaev/highlight.js/tree/master/src/styles)目录中找到支持的主题的完整列表。

### 注册其他语言

尽管 Highlight.js 支持[许多开箱即用的语言](https://highlightjs.org/static/demo/)，但您可能需要注册其他语言支持。 对于这些情况，我们通过暴露 `hljs` 常量作为 `highlight` 配置键的一部分来提供接口。 这可以让你调用 [`registerLanguage`](http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language)：

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