Translate api-doc-markdown

docs/api-doc-markdown.md

@@ -1,21 +1,18 @@
----
-id: doc-markdown
-title: Markdown Features
----
+# Markdown 功能
 
-## Markdown Headers
+## Markdown 头部
 
-### Documents
+### 文档
 
-Documents use the following markdown header fields that are enclosed by a line `---` on either side:
+文档使用下面的 markdown 头部字段，这两个标题字段在两边用 `---` 括起来：
 
-`id`: A unique document id. If this field is not present, the document's `id` will default to it's file name (without the extension).
+`id`：一个唯一的文件 ID。 如果这个字段不存在，文档的 id 将默认为文件名（不包括扩展名）。
 
-`title`: The title of your document. If this field is not present, the document's `title` will default to it's `id`.
+`title`：文档的标题。 如果这个字段不存在，文档的 `title` 将默认为 `id`。
 
-`sidebar_label`: The text shown in the document sidebar for this document. If this field is not present, the document's `sidebar_label` will default to its `title`.
+`sidebar_label`：文档边栏中显示的文本。 如果该字段不存在，文档的 `sidebar_label` 将默认为其 `title`。
 
-For example:
+示例:
 
 ```markdown
 ---
@@ -25,9 +22,9 @@ sidebar_label: Document
 ---
 ```
 
-Versioned documents have their ids altered to include the version number when they get copied. The new `id` is `version-${version}-${id}` where `${version}` is the version number of that document and `${id}` is the original `id`. Additionally, versioned documents get an added `original_id` field with the original document id.
+版本化的文档在被复制时将其 ID 更改为包含版本号。 新的 `id` 是 `version-${version}-${id}`，其中 `${version}` 是该文档的版本号， `${id}` 是原始的 `id`。 此外，版本化的文档还会获得原始文档 ID 添加成的 `original_id` 字段。
 
-For example:
+示例:
 
 ```markdown
 ---
@@ -38,19 +35,19 @@ original_id: doc1
 ---
 ```
 
-### Blog Posts
+### 博客博文
 
-Blog Posts use the following markdown header fields that are enclosed by a line `---` on either side:
+博客博文使用以下 markdown 头部字段标记，在两边都用一行 `---` 括起来：
 
-`title`: The title of this blog post.
+`title`：这篇博文的标题。
 
-`author`: The author of this blog post. If this field is omitted, no author name will be shown.
+`author`：这篇博文的作者。 如果该字段被省略，则不会显示作者姓名。
 
-`authorURL`: A page to link to when a site user clicks the author's name. If this field is omitted, the author's name will not link to anything.
+`authorURL`：网站用户点击作者姓名时要链接的页面。 如果这个字段被省略，作者的名字将不会链接到任何东西。
 
-`authorFBID`: The author's Facebook id, used only to get the author's profile picture to display with the blog post. If this field is omitted, no author picture will be shown for the blog post.
+`authorFBID`：作者的 Facebook 标识，只用于获取作者的个人资料图片以显示博客文章。 如果此字段被忽略，则不会显示作者图片的博客文章。
 
-For example:
+示例:
 
 ```markdown
 ---
@@ -61,41 +58,41 @@ authorFBID: 100002976521003
 ---
 ```
 
-## Extra Features
+## 额外功能
 
-Docusaurus supports some extra features when writing documentation in markdown.
+在使用 Markdown 编写文档时，Docusaurus 支持一些额外的功能。
 
-### Linking other Documents
+### 链接其他文档
 
-You can use relative urls to other documentation files which will automatically get converted to the corresponding html links when they get rendered.
+你可以使用相对的 URL 到其他文档文件，当它们被渲染时，它们会自动转换成相应的 html 链接。
 
-Example:
+示例:
 
 ```markdown
 [This links to another document](other-document.md)
 ```
-This markdown will automatically get converted into a link to `/docs/other-document.html` (or the appropriately translated/versioned link) once it gets rendered.
 
-This can help when you want to navigate through docs on GitHub since the links there will be functional links to other documents (still on GitHub), but the documents will have the correct html links when they get rendered.
+这个 markdown 会自动转换成一个链接到 `/docs/other-document.html` （或适当的 翻译/版本）的链接。
 
-### Linking to Images and Other Assets
+当你想浏览 GitHub 上的文档时，这可能会有所帮助，因为链接将会链接到其他文档（仍然在 GitHub 上），但是文档在呈现时会有正确的HTML链接。
 
-Static assets can be linked to in the same way that documents are, using relative urls. Static assets used in documents and blogs should go into `docs/assets` and `website/blog/assets`, respectively. The markdown will get converted into correct link paths so that these paths will work for documents of all languages and versions.
+### 链接到图像和其他资源
 
-Example:
+静态资源可以通过使用相对 URL 链接到文档相同的方式。 文档和博客中使用的静态资源应该分别进入 `docs/assets` 和 `website/blog/assets`。 Markdown 将被转换成正确的链接路径，以便这些路径将适用于所有语言和版本的文档。
+
+示例:
 
 ```markdown
 ![alt-text](assets/doc-image.png)
 ```
 
+### 生成目录
 
-### Generating Table of Contents
-
-You can make an autogenerated list of links, which can be useful as a table of contents for API docs.
+您可以创建自动生成的链接列表，这些链接可以用作 API 文档的目录。
 
-In your markdown file, insert a line with the text <`AUTOGENERATED_TABLE_OF_CONTENTS`>. Write your documentation using `h3` headers for each function inside a code block. These will be found by Docusaurus and a list of links to these sections will inserted at the text <`AUTOGENERATED_TABLE_OF_CONTENTS`>.
+在您的 markdown 文件中，插入一行为 <`AUTOGENERATED_TABLE_OF_CONTENTS`> 的文字。 用代码块中的每个函数的 `h3` 头文件写你的文档。 这些将被 Docusaurus 找到，并且这些部分的链接列表将被插入到文本 <`AUTOGENERATED_TABLE_OF_CONTENTS`> 中。
 
-Example:
+示例:
 
 ```markdown
 ### `docusaurus.function(a, b)`
@@ -108,18 +105,18 @@ Text describing my function
 Text describing my function
 ```
 
-will lead to a table of contents of the functions:
+将生成目录的功能：
 
 ```markdown
 - `docusaurus.function(a, b)`
 - `docdoc(file)`
 ```
 
-and each function will link to their corresponding sections in the page.
+每个函数都会链接到页面中的相应部分。
 
-## Syntax Highlighting
+## 语法高亮
 
-Syntax highlighting is enabled by default on fenced code blocks. The language should be detected automatically, but you can sometimes get better results by specifying the language. You can do so using an [info string](https://github.github.com/gfm/#example-111), following the three opening backticks. The following JavaScript example...
+隔离的代码块默认启用语法高亮显示。 会自动检测语言，但通过指定语言，您有时可以获得更好的结果。 您可以使用[信息字符串](https://github.github.com/gfm/#example-111)，在三个开启反引号之后这样做。 以下JavaScript示例...
 
     ```javascript
     ReactDOM.render(
@@ -128,7 +125,7 @@ Syntax highlighting is enabled by default on fenced code blocks. The language sh
     );
     ```
 
-...would be rendered with syntax highlighting like so:
+...会像语法高亮显示一样：
 
 ```javascript
 ReactDOM.render(
@@ -137,7 +134,7 @@ ReactDOM.render(
 );
 ```
 
-Highlighting is provided by [Highlight.js](https://highlightjs.org) using the theme specified in your `siteConfig.js` file as part of the `highlight` key:
+高亮显示由 [Highlight.js](https://highlightjs.org) 使用 `siteConfig.js` 文件中指定的主题作为 `highlight` 键的一部分提供：
 
 ```javascript
 highlight: {
@@ -145,11 +142,11 @@ highlight: {
 }
 ```
 
-You can find the full list of supported themes in the Highlight.js [`styles`](https://github.com/isagalaev/highlight.js/tree/master/src/styles) directory.
+您可以在 Highlight.js [`styles`](https://github.com/isagalaev/highlight.js/tree/master/src/styles)目录中找到支持的主题的完整列表。
 
-### Registering additional languages
+### 注册其他语言
 
-While Highlight.js provides support for [many popular languages out of the box](https://highlightjs.org/static/demo/), you may find the need to register additional language support. For these cases, we provide an escape valve by exposing the `hljs` constant as part of the `highlight` config key. This in turn allows you to call [`registerLanguage`](http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language):
+尽管 Highlight.js 支持[许多开箱即用的语言](https://highlightjs.org/static/demo/)，但您可能需要注册其他语言支持。 对于这些情况，我们通过暴露 `hljs` 常量作为 `highlight` 配置键的一部分来提供接口。 这可以让你调用 [`registerLanguage`](http://highlightjs.readthedocs.io/en/latest/api.html#registerlanguage-name-language)：
 
 ```javascript
 highlight: {