跳至主要内容

如何在不到两小时内将 Profilo 转换为 Docusaurus

·阅读时长：6 分钟
Christine Abernathy
Christine Abernathy

“Joel 和我讨论过网站，以及如果能用它来启动会很棒。所以我挑战自己添加 Docusaurus 支持。我花了不到一个半小时。我将向您发送一个包含添加内容的 PR，以便您查看并看看是否喜欢。您添加文档的工作流程与编辑这些 Markdown 文件没什么不同。”

——发送给 Profilo 团队的笔记

这是使用 Docusaurus 创建 Profilo 网站的相当短的旅程的故事。

Profilo 是一个用于从生产环境中收集性能跟踪的 Android 库，于今年早些时候宣布。该项目 发布在 GitHub 上，其中有不到 几个 Markdown 文件 来描述其功能，并且没有网站来展示任何品牌并突出显示徽标。手头的任务是将这些现有文档和徽标转换为网站。

通常，在使用 Docusaurus 创建网站时，您会执行以下操作：

  1. 使用 Docusaurus 脚本生成一个模板网站。
  2. 自定义生成的模板文件以符合您所需的网站颜色和项目配置（例如：网站和 GitHub 链接）。
  3. 创建网站内容
    1. 添加您的文档和任何支持的资产。
    2. 自定义 Docusaurus 提供的默认着陆页以满足您的需求。
    3. 配置默认网站导航文件。
  4. 发布网站并设置其发布方式以供将来更改。

鉴于我已经拥有预先存在的 Markdown 文件，因此我不必生成核心内容，只需确保 Docusaurus 可以通过向它们添加预期的元数据来处理这些文件。因此，大部分工作将集中在自定义 Docusaurus 提供的默认值。

所采取步骤的概述​

以下是将网站转换为网站所采取步骤的概述。我将在后面的部分讨论一些设计方面。

设计和颜色

  1. 从设计师那里获得所有所需的徽标格式。我必须创建 .favicon 文件。
  2. 使用 http://paletton.com/ 工具（非常方便！）设计出一些可以接受的网站主色调和辅助色调。

初始网站设置

  1. 在 GitHub 上为 Profilo 项目 创建了一个分支，并创建了一个本地克隆来设置网站。
  2. 使用 安装说明 创建了初始 Docusaurus 网站。
  3. 删除了 docs-examples-from-docusaurus 和 website/blog-examples-from-docusaurus 文件夹，因为这些文件夹将不再需要。Profilo 有现有的文档供我们使用，并且此时不需要博客。

内容创建

  1. 向 docs 文件夹中找到的现有 Markdown 文件添加元数据，例如：

    ---
    id: architecture
    title: Architecture
    sidebar_label: Architecture
    ---

  2. 将徽标资产添加到 website/static/img 文件夹。

  3. 修改 website/pages/en/index.js（着陆页），以突出显示 Profilo 功能。

  4. 修改 website/core/Footer.js（页脚），以简化 Profilo 的页脚。

  5. 编辑 website/siteConfig.js（网站配置文件）以指定先前选择的主色调和辅助色调。

  6. 修改 website/sidebars.json，该文件指定侧边栏导航。列出所有文档并根据添加到 Markdown 文件的元数据对其进行自定义。

  7. 编辑网站配置文件以指定 GitHub 属性、徽标图像、标题链接和网站链接。

  8. 在整个阶段本地测试网站。（我在 website 文件夹中运行 yarn start 来启动服务器。）

反馈和审查更改

  1. 向该项目发送了一个 pull request。
  2. 在设计师正确地对我的选择（IANAD）感到惊讶之后，更新了颜色。
  3. 更新了颜色并更新了 PR。
  4. 然后 PR 被接受并 合并。耶！

网站发布

  1. 通过从命令行运行 Docusaurus 发布脚本，将第一个网站版本推送到远程仓库

    USE_SSH=true \
      GIT_USER=caabernathy \
      CURRENT_BRANCH=master \
      yarn run publish-gh-pages

  2. 使用 提供的 Docusaurus 说明 配置 CircleCI。为此创建了 2 个 PR，第一个用于初始配置，第二个用于确保 CircleCI 仅针对主分支中的更改触发（感谢 Joel Marcey！）。

最终网站发布在 https://facebookincubator.github.io/profilo/ 上。从到达第一个 PR 阶段到响应审查反馈并发布网站，总共花费了 1.5 个小时。

设计​

以下是发送第一个 pull request 时初始网站的外观

The website's front page, with a quite bright and saturated red color as the primary color, closely resembling the Profilo logo color, making the logo unrecognizable in the navbar

在内容创建方面，大部分时间都花在了选择与给定徽标合理匹配的颜色上。这些颜色是设计师反馈的良好起点。我使用 Photoshop 对徽标的各个部分进行采样。

Picking colors in Photoshop, with the Profilo logo and the main working area in the background and a color picker dialog in the foreground, selected to a red shade

然后，我将该颜色的 RGB 表示设置为 Paletton 上的基准色。然后，该网站通过编辑 Docusaurus 网站配置文件，为我提供了各种颜色选项，供我在网站上尝试。

Using Paletton to generate a full palette from the red shade selected. There's a color wheel showing all hues on the left, and a square showing various shades of red on the right.

选择的主色调和辅助色调是设计师反馈的良好起点。

Docusaurus 生成的默认网站也进行了修改。这些更改主要围绕简化页脚和为 Profilo 创建自定义着陆页，其中列出了该项目的特性。

以下是最终网站的外观

The website's front page, with a much darker red color as the primary color, making both the logo and the primary-colored title text clearly legible.

这是一个示例页面，显示了核心内容，在本例中为“入门”页面

A doc page with the sidebar on the left quarter of the screen and the main content occupying the rest. Some text is using the primary color and the main body uses multiple kinds of typesetting including bold, list, and code

这也显示了通过编辑 website/sidebars.json 设置的侧边栏结构。

最后，我不必担心处理响应式设计。Docusaurus 开箱即用地提供此功能！

Mobile screenshots of the front page and sample doc page. The layout is automatically adjusted to make it appear more natural. The doc sidebar is hidden behind a button.

最终想法​

Profilo 工程师很高兴看到他们不必更改工作流程来更新现有内容。他们能够继续使用 Markdown 文件。如果将来添加了新文档，这仍然是正确的，尽管如果需要更新侧边栏导航，可能需要进行一些配置更改。

Docusaurus 提供的基础设施使得将 Markdown 文件转换为可工作的网站变得容易。即使该项目只有三个文档，这也让 Profilo 看起来更专业。因此，这很值得花短时间来完成它。