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 支持, 謝謝.