Facebook Docusaurus 中文文檔 頁面和樣式

此係列文章的應用示例已發佈於 GitHub: docusaurus-docs-Zh_CN. 能夠 Fork 幫助改進或 Star 關注更新. 歡迎 Star.

頁面和樣式

Docusaurus 支持在 website/pages 文件夾中將頁面編寫爲 React 組件，該文件夾將與網站的其餘部分共享相同的頁眉，頁腳和樣式。

頁面的 URL

website/pages 中的任何 .js 文件將使用 "pages" 以後的文件路徑呈現爲靜態 html。 website/pages/en 中的文件也將被複制到 pages 中，並將覆蓋 pages 中的任何同名文件。 例如，website/pages/en/help.js 文件的頁面能夠在 URL ${baseUrl}en/help.js 以及 URL ${baseUrl}help.js 中找到。其中 ${baseUrl} 是在 siteConfig.js 文件中設置的 baseUrl 字段。

頁面請求路徑

Docusaurus 提供了一些有用的 React 組件供用戶編寫他們本身的頁面，能夠在 CompLibrary 模塊中找到。這個模塊是在 node_modules/docusaurus 中做爲 Docusaurus 的一部分提供的，因此爲了訪問它，在渲染爲靜態 html 時，pages 文件夾中的頁面被臨時複製到 node_modules/docusaurus 中。如示例文件所示，這意味着位於 pages/en/index.js 的用戶頁面使用 "../../core/CompLibrary.js" 的 require 路徑導入提供的組件。

這對用戶意味着若是你想使用 CompLibrary 模塊，請確保 require 路徑設置正確。例如，在 page/mypage.js 中的一個頁面將使用一個路徑 "../core/CompLibrary.js"。

若是你想在你的網站文件夾中使用你本身的組件，可使用 process.cwd() 來引用 website 文件夾來構建 require 路徑。例如，若是你添加一個組件到 website/core/mycomponent.js，你可使用 require 路徑，"process.cwd() + /core/mycomponent.js"。

提供的組件

Docusaurus 在 CompLibrary 中提供瞭如下組件：

CompLibrary.MarkdownBlock

一個 React 組件，用於解析 markdown 並呈現給 HTML。

示例:

const MarkdownBlock = CompLibrary.MarkdownBlock;

<MarkdownBlock>[Markdown syntax for a link](http://www.example.com)</MarkdownBlock>

CompLibrary.Container

使用 Docusaurus 樣式的 React 容器組件。 有可選的填充和背景顏色屬性，您能夠配置。

填充選擇: all, bottom, left, right, top.
背景選擇: dark, highlight, light.

示例:

<Container padding={["bottom", "top"]} background="light">
  ...         
</Container>

CompLibrary.GridBlock

一個 React 組件來組織文本和圖像。

align 屬性肯定文本對齊。 文本對齊方式默認爲 left，能夠設置爲 center 或 right。

layout 屬性肯定每一個 GridBlock 的列部分的數量。 layout 默認爲 twoColumn，也能夠設置爲 threeColumn 或 fourColumn。

contents 屬性是一個包含 GridBlock 每一個部份內容的數組。 每一個內容對象能夠有如下字段：

• content 是從 markdown 解析的章節文本
• image 顯示圖片的路徑
• imageAlign 字段用於圖像對齊，相對於文本，默認爲 top ，能夠設置爲 bottom, left, 或 right
• title 是從 markdown 解析的要顯示的標題
• imageLink 是點擊圖像連接目的地的

示例:

<GridBlock
  align="center"
  contents={[
    {
      content: "Learn how to use this project",
      image: siteConfig.baseUrl + "img/learn.png",
      title: `[Learn](${siteConfig.baseUrl}docs/tutorial.html)`,
      imageLink: siteConfig.baseUrl + "docs/tutorial.html"
    },
    {
      content: "Questions gathered from the community",
      image: siteConfig.baseUrl + "img/faq.png",
      imageAlign: "top",
      title: "Frequently Asked Questions"
    },
    {
      content: "Lots of documentation is on this site",
      title: "More"
    }
  ]}
  layout="threeColumn"
/>

在生成的示例文件 以及 Docusaurus 本身的網站設置 repo 中，能夠找到更多關於如何使用這些組件的例子。

翻譯字符串

啓用翻譯後，website/pages/en 內的任何頁面都將被翻譯爲全部已啓用的語言。 非英文網頁的網址將使用 languages.js 文件中指定的語言標記。 例如。 法語頁面 website/pages/en/help.js 的網址能夠在 ${baseUrl}fr/help.html 處找到。

在編寫要翻譯的頁面時，能夠將任何要翻譯的字符串包裝在 <translate> 標籤中。 例如

<p><translate>I like translations</translate></p>

您還能夠提供一個可選的說明屬性，爲翻譯人員提供上下文。 例如

<a href="/community">
  <translate desc="footer link to page referring to community github and slack">Community</translate>
</a>

添加如下require語句：

const translate = require("../../server/translate.js").translate;

請注意，這個路徑對 pages/en 裏面的文件是有效的，若是文件位於不一樣的位置，就應該相應地進行調整，正如上面討論的那樣。

使用靜態資源

靜態資源應該放在 website/static 文件夾中。 他們能夠經過他們的路徑訪問，不包括 "static"。 例如，若是該網站的 baseUrl 爲 "/docusaurus/"，website/static/img/logo.png 中的圖片可用 /docusaurus/img/logo.png。

樣式

您應該使用 siteConfig 中的 colors 字段來配置您的網站的主要，輔助和代碼塊顏色，如這裏所示。 你也能夠像 siteConfig 文檔中描述的那樣配置其餘顏色。

您能夠經過在 website/static 文件夾中的任何位置添加自定義樣式。 您在 static 文件夾中提供的任何 .css 文件將鏈接到 Docusaurus 提供的樣式的末尾，容許您根據須要添加或覆蓋 Docusaurus 默認樣式。

一個簡單的方法來找出你想要覆蓋或添加到什麼類是本地啓動您的服務器，並使用您的瀏覽器的檢查元素工具。

若是這篇文章對您有幫助, 感謝 下方點贊 或 Star GitHub: docusaurus-docs-Zh_CN 支持, 謝謝.