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