Markdown Features
Markdown 标题
文档
文档使用以下 markdown 协议头字段, 它们由两侧的行 --- 括起来:
id: A unique document id. If this field is not present, the document's id will default to its file name (without the extension).
title: The title of your document. If this field is not present, the document's title will default to its id.
hide_title: Whether to hide the title at the top of the doc.
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.
例如：
---
id: doc1
title: My Document
sidebar_label: Document
---
经过版本控制的文档在被复制时会更改其 id 这样才能包含版本号。 新的 id 为 version-${version}-${id}, 其中 ${version} 是该文档的版本号, $ {id} 是原始的 id。 此外，版本文档可得到original_id 文件，使用原版的文件id。
例如：
---
id: version-1.0.0-doc1
title: My Document
sidebar_label: Document
original_id: doc1
---
custom_edit_url: The url for editing this document. If this field is not present, the document's edit url will fallback to editUrl from optional fields of siteConfig.js. See siteConfig.js docs for more information.
例如：
---
id: doc-markdown
title: Markdown Features
custom_edit_url: https://github.com/facebook/Docusaurus/edit/master/docs/api-doc-markdown.md
---
博客文章
博客文章使用以下markdown字段, 它们由两边的行 --- 括起来:
tittle: 此博客文章的标题。
author: The author of this blog post. If this field is omitted, no author name will be shown.
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.
authorFBID: 作者的 Facebook（脸书） id, 仅用于让作者的个人资料图片显示在博客文章中。 如果省略此字段, 则不会显示该作者的图片在这篇文章中。
例如：
---
tittle: My First Blog Post
author: Frank Li
authorURL: http://twitter.com/franchementli
authorFBID: 100002976521003
---
更多功能
Docusaurus 在markdown中编写文档时支持一些额外的功能。
链接到其他文档
您可以使用相关urls 链接到其他文档文件, 这样它们将自动转换为相应的 html 链接。
例如：
[This links to another document](other-document.md)
这样, markdown将把它自动转换成指向 /docs/other-document.html 的链接(或适当翻译/版本控制链接) 。
这可以帮助您在 GitHub 上浏览文档, 因为这样的链接将会功能链接到其他文档 (但仍在 GitHub), 但文档在得到渲染时将具有正确的 html 链接。
链接到图像和其它资源
使用相关 url 可以以与文档相同的方式链接静态资源。 在文档和博客中使用的静态资产应分别进入 docs/assets 和 website/blog/assets。 Markdown 被转换成正确的链接路径, 这样这些路径就能为所有语言和版本的文档所用。
例如：
生成目录
您可以制作一个自动生成的链接列表, 它可以作为 API 文档的目录使用。
In your markdown file, insert a line with the text <AUTOGENERATED_TABLE_OF_CONTENTS>. 使用 h3 为标题在代码块里为每个函数编写文档。 These will be found by Docusaurus and a list of links to these sections will inserted at the text <AUTOGENERATED_TABLE_OF_CONTENTS>.
例如：
### `docusaurus.function(a, b)`
Text describing my function
### `docdoc(file)`
Text describing my function
这将会把页面带去这些功能的目录：
- `docusaurus.function(a, b)`
- `docdoc(file)`
每个函数将会把链接带到页面相对应的部分。
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, following the three opening backticks. The following JavaScript example...
```javascript
ReactDOM.render(
<h1>Hello, world!</h1>,
document.getElementById('root')
);
```
...would be rendered with syntax highlighting like so:
ReactDOM.render(
<h1>Hello, world!</h1>,
document.getElementById('root')
);
Highlighting is provided by Highlight.js using the theme specified in your siteConfig.js file as part of the highlight key:
highlight: {
theme: 'default'
}
You can find the full list of supported themes in the Highlight.js styles directory.
Registering additional languages
While Highlight.js provides support for many popular languages out of the box, 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:
highlight: {
theme: 'default',
hljs: function(hljs) {
hljs.registerLanguage('galacticbasic', function(hljs) {
// ...
});
}
}