作者：
100% Markdown 远征
2021 年 6 月，我们决定开始将 MDN Web 文档的源代码从 HTML 转换为一种对我们来说更易于使用的格式。目标是将我们所有手动编写的文档转换为 Markdown，对于这次特殊的远征，我们确实需要攀登一座源代码的山峰。
在这篇文章中，我们将描述我们决定迁移到 Markdown 的原因，以及您为帮助我们完成任务可以采取的步骤。
为什么要实现 100% Markdown？
我们希望将 MDN Web 文档上所有活动内容都转换为 Markdown，原因如下：
- Markdown 是一种更易于理解和友好的方式，可以用于为 MDN Web 文档内容做出贡献。将所有内容都转换为 Markdown 将有助于在所有语言和存储库之间创建一个统一的贡献体验。
- 当所有内容都使用 Markdown 时，MDN 工程团队将能够清理大量当前维护的代码。减少维护的代码量将使他们能够专注于改进编写者和贡献者的工具。更好的工具将带来更愉快的贡献工作流程。
- 所有内容都转换为 Markdown 将允许 MDN Web 文档团队在所有活动语言上运行相同的代码风格检查规则。
这是在翻译内容存储库中有关该项目的 跟踪问题。
工具
本节介绍您参与此项目所需的工具。
Git
如果您没有安装 Git，可以按照此入门页面中介绍的步骤操作。
https://git-scm.cn/book/en/v2/Getting-Started-Installing-Git
如果您使用的是 Linux 或 macOS，您可能已经安装了 Git。要检查，请打开终端并运行：git --version
在 Windows 上，有几个选项
GitHub
我们在 GitHub 上跟踪源代码和管理贡献，因此需要以下内容
• 一个 GitHub 帐户。
• GitHub CLI 以遵循以下命令。（鼓励使用，但可选，即如果您已经习惯使用 Git，您可以在无需使用 GitHub CLI 的情况下完成所有相同的任务。）
Nodejs
首先，安装 nvm – https://github.com/nvm-sh/nvm#installing-and-updating 或在 Windows 上使用 https://github.com/coreybutler/nvm-windows
安装完上述所有内容后，使用 NVM 安装 Nodejs 版本 16
nvm install 16
nvm use 16
node --version这将输出一个类似于 v16.15.1 的 Nodejs 版本号。
存储库
此项目需要来自多个存储库的代码和内容，如下所示。
您只需要分叉 translated-content 存储库即可。我们将直接克隆另外两个存储库。
使用 GitHub CLI 克隆上述存储库和您的 translated-content 分叉：
gh repo clone mdn/markdown
gh repo clone mdn/content
gh repo clone username/translated-content # replace username with your GitHub username设置转换工具
cd markdown
yarn您还需要通过 .env 文件添加一些配置。在目录的根目录中，创建一个名为 .env 的新文件，内容如下
CONTENT_TRANSLATED_ROOT=../translated-content/files设置内容存储库
cd .. # This moves you out of the `markdown` folder
cd content
yarn转换为 Markdown
我将在本文档中介绍一些特定的命令，但有关详细文档，请查看 markdown 存储库的 README。
我们维护着一个需要转换为 Markdown 的文档列表 在此 Google 表格中。每个语言都有一个工作表。工作表按每种语言要转换的文档数量排序 - 从最少到最多。您不必理解语言就能进行转换。只要您熟悉 Markdown 和一些 HTML，您就可以做出贡献。
注意：您可以在 我们的文档 中找到对 MDN Web 文档支持的 Markdown 版本的有用 参考。虽然有一些自定义，但总的来说，它基于 GitHub 风格 Markdown。
步骤
创建问题
在 translated-content 存储库 中，转到“问题”选项卡，然后单击“新建问题”按钮。如引言中所述，此工作有一个跟踪问题，因此最好在您要创建的问题中引用跟踪问题。
单击“新建问题”按钮后，将出现三个选项。对于我们的目的，我们将选择“打开一个空白问题”选项。对于问题的标题，使用类似“chore: convert mozilla/firefox/releases for Spanish to Markdown”的内容。在描述中，您可以添加以下内容
作为更大的 100% Markdown 项目 的一部分，我正在将 mozilla/firefox/releases 下的文档集转换为 Markdown。
注意：您很可能无法将问题分配给自己。这里最好的做法是提及相应 语言环境 的本地化 团队成员 并要求他们将问题分配给您。例如，在 GitHub 上，您可以添加类似以下内容的注释：“您好 @mdn/yari-content-es 我想处理此问题，请将其分配给我。谢谢！”
您可以在 此处找到团队列表。
更新电子表格
跟踪电子表格包含一些字段，如果您打算处理特定项目，则应更新这些字段。您需要添加的第一项是您的 GitHub 用户名，并将文本链接到您的 GitHub 个人资料。其次，将状态设置为“进行中”。在“问题”列中，粘贴您在上一步中创建的问题的链接。
创建特性分支
在使用 Git 和 GitHub 的项目中，通常遵循 特性分支工作流程。因此，我需要为 translated-content 存储库上的工作创建一个特性分支。为此，我们将再次使用我们的问题作为参考。
假设您的问题称为“chore: convert mozilla/firefox/releases for Spanish to Markdown”，ID 为 8192。您将在 translated-content 存储库文件夹的根目录中执行以下操作
注意：翻译内容存储库是一个非常活跃的存储库。在创建特性分支之前，请确保使用命令
git pull upstream main从远程拉取最新内容
git pull upstream main
git switch -c 8192-chore-es-convert-firefox-release-docs-to-markdown注意：在旧版本的 Git 中，您需要使用
git checkout -B 8192-chore-es-convert-firefox-release-docs-to-markdown。
上面的命令将创建特性分支并切换到该分支。
运行转换
现在，您已准备好进行转换。Markdown 转换工具有几种模式可以运行
- dry – 运行脚本，但不实际写入任何输出
- keep – 运行脚本并进行转换，但不删除 HTML 文件
- replace – 进行转换并删除 HTML 文件
您几乎总是从 dry 运行开始。
注意：在运行以下命令之前，请确保您位于 markdown 存储库的根目录中。
yarn h2m mozilla/firefox/releases --locale es --mode dry这是因为转换工具有时会遇到无法知道如何转换文档部分的情况。markdown 工具将生成一份包含遇到的错误详细信息的报告。例如
# Report from 9/1/2022, 2:40:14 PM
## All unhandled elements
- li.toggle (4)
- dl (2)
- ol (1)
## Details per Document
### [/es/docs/Mozilla/Firefox/Releases/1.5](<https://mdn.org.cn/es/docs/Mozilla/Firefox/Releases/1.5>)
#### Invalid AST transformations
##### dl (101:1) => listItem
type: "text"
value: ""
### [/es/docs/Mozilla/Firefox/Releases/3](<https://mdn.org.cn/es/docs/Mozilla/Firefox/Releases/3>)
### Missing conversion rules
- dl (218:1)
报告的第一行指出该工具在转换 li.toggle 的四个实例时遇到了问题。因此，有四个列表项的 class 属性设置为 toggle。在更大的报告中，有以下部分
### [/es/docs/Mozilla/Firefox/Releases/9](<https://mdn.org.cn/es/docs/Mozilla/Firefox/Releases/9>)
#### Invalid AST transformations
##### ol (14:3) => list
type: "html"
value: "<li class=\\"toggle\\"><details><summary>Notas de la Versión para Desarrolladores de Firefox</summary><ol><li><a href=\\"/es/docs/Mozilla/Firefox/Releases\\">Notas de la Versión para Desarrolladores de Firefox</a></li></ol></details></li>",type: "html"
value: "<li class=\\"toggle\\"><details><summary>Complementos</summary><ol><li><a href=\\"/es/Add-ons/WebExtensions\\">Extensiones del navegador</a></li><li><a href=\\"/es/Add-ons/Themes\\">Temas</a></li></ol></details></li>",type: "html"
value: "<li class=\\"toggle\\"><details><summary>Firefox por dentro</summary><ol><li><a href=\\"/es/docs/Mozilla/\\">Proyecto Mozilla (Inglés)</a></li><li><a href=\\"/es/docs/Mozilla/Gecko\\">Gecko</a></li><li><a href=\\"/es/docs/Mozilla/Firefox/Headless_mode\\">Headless mode</a></li><li><a href=\\"/es/docs/Mozilla/JavaScript_code_modules\\">Modulos de código JavaScript (Inglés)</a></li><li><a href=\\"/es/docs/Mozilla/js-ctypes\\">JS-ctypes (Inglés)</a></li><li><a href=\\"/es/docs/Mozilla/MathML_Project\\">Proyecto MathML</a></li><li><a href=\\"/es/docs/Mozilla/MFBT\\">MFBT (Inglés)</a></li><li><a href=\\"/es/docs/Mozilla/Projects\\">Proyectos Mozilla (Inglés)</a></li><li><a href=\\"/es/docs/Mozilla/Preferences\\">Sistema de Preferencias (Inglés)</a></li><li><a href=\\"/es/docs/Mozilla/WebIDL_bindings\\">Ataduras WebIDL (Inglés)</a></li><li><a href=\\"/es/docs/Mozilla/Tech/XPCOM\\">XPCOM</a></li><li><a href=\\"/es/docs/Mozilla/Tech/XUL\\">XUL</a></li></ol></details></li>",type: "html"
value: "<li class=\\"toggle\\"><details><summary>Crear y contribuir</summary><ol><li><a href=\\"/es/docs/Mozilla/Developer_guide/Build_Instructions\\">Instrucciones para la compilación</a></li><li><a href=\\"/es/docs/Mozilla/Developer_guide/Build_Instructions/Configuring_Build_Options\\">Configurar las opciones de compilación</a></li><li><a href=\\"/es/docs/Mozilla/Developer_guide/Build_Instructions/How_Mozilla_s_build_system_works\\">Cómo funciona el sistema de compilación (Inglés)</a></li><li><a href=\\"/es/docs/Mozilla/Developer_guide/Source_Code/Mercurial\\">Código fuente de Mozilla</a></li><li><a href=\\"/es/docs/Mozilla/Localization\\">Localización</a></li><li><a href=\\"/es/docs/Mozilla/Mercurial\\">Mercurial (Inglés)</a></li><li><a href=\\"/es/docs/Mozilla/QA\\">Garantía de Calidad</a></li><li><a href=\\"/es/docs/Mozilla/Using_Mozilla_code_in_other_projects\\">Usar Mozilla en otros proyectos (Inglés)</a></li></ol></details></li>"
因此，问题出在文件 /es/docs/Mozilla/Firefox/Releases/9 中。在这种情况下，我们可以忽略它，因为我们只需将 HTML 保持在 Markdown 中即可。这有时是必要的，因为我们需要的 HTML 无法在 Markdown 中准确表示。您在上面输出中看不到的部分是文件的这部分
<div><section id="Quick_links">
<ol>
<li class="toggle">
如果您在主 content 存储库中搜索，您会发现很多此类实例。在所有这些情况下，您会看到 HTML 保持原样，并且此部分没有转换为 Markdown。
接下来的两个有问题项是两个 dl 或描述列表元素。这些元素需要使用 我们的文档 中的指南进行手动转换。最后一个项目 ol 实际上与 li.toggle 问题有关。这些列表项由 ol 包裹，由于工具不确定如何处理列表项，因此它也抱怨有序列表项。
现在我们已经了解了问题所在，我们有两个选择。我们可以运行完全相同的命令，但这次使用`replace`模式，或者我们可以使用`keep`模式。我将继续使用`replace`运行命令。虽然之前的命令实际上并没有向翻译内容存储库写入任何内容，但在使用`replace`运行时，它将创建一个名为`index.md`的新文件，其中包含转换后的 Markdown，并删除位于同一目录中的`index.html`。
yarn h2m mozilla/firefox/releases --locale es --mode replace根据报告中的指南，我将不得不特别注意转换后的以下文件
/es/docs/Mozilla/Firefox/Releases/1.5
/es/docs/Mozilla/Firefox/Releases/3
/es/docs/Mozilla/Firefox/Releases/9
运行命令后，在翻译内容存储库文件夹的根目录下运行以下命令：`git status`。这将向您显示命令所做更改的列表。根据所触及文件的数量，输出可能很冗长。需要注意的是，您没有预料到的文件夹或文件没有发生任何变化。
测试更改
现在转换已经完成，我们需要检查语法并确保页面正确呈现。这就是`content`存储库发挥作用的地方。与`markdown`存储库一样，我们还需要在内容文件夹的根目录下创建一个`.env`文件。
CONTENT_TRANSLATED_ROOT=../translated-content/files有了这个，我们就可以启动开发服务器并在浏览器中查看页面了。要启动服务器，请运行`yarn start`。您应该看到以下输出
❯ yarn start
yarn run v1.22.17
$ yarn up-to-date-check && env-cmd --silent cross-env CONTENT_ROOT=files REACT_APP_DISABLE_AUTH=true BUILD_OUT_ROOT=build yari-server
$ node scripts/up-to-date-check.js
[HPM] Proxy created: / -> <https://mdn.org.cn>
CONTENT_ROOT: /Users/schalkneethling/mechanical-ink/dev/mozilla/content/files
Listening on port 5042
打开http://localhost:5042，它将提供主页。要查找已转换页面的 URL 之一，请打开 Markdown 文件并查看前置数据的 slug。当您之前运行`git status`时，它会将文件路径打印到终端窗口。文件路径将准确地显示您在哪里可以找到文件，例如，`files/es/mozilla/firefox/releases/1.5/index.md`。在您选择的编辑器中打开文件。
在前置数据中，您将找到以下条目
slug: Mozilla/Firefox/Releases/1.5
要在浏览器中加载页面，您始终要在 slug 前添加`http://localhost:5042/es/docs/`。换句话说，您将在浏览器中打开的最终 URL 将是`http://localhost:5042/es/docs/Mozilla/Firefox/Releases/1.5`。您可以在单独的选项卡中打开页面的英文版本进行比较，但请注意，内容可能会有很大差异，因为您可能转换了一个一段时间没有更新的页面。
您要留意的是页面中任何看起来没有正确呈现的内容。如果您发现看起来不正确的内容，请查看 Markdown 文件并查看您是否可以找到任何看起来不正确或完全损坏的语法。使用像VSCode这样的工具，安装了Markdown 工具和Prettier会非常有用。
即使呈现的内容看起来不错，也请花点时间浏览生成的 Markdown 并查看 linter 是否会提出任何可能的错误。
注意：如果您看到类似于{{FirefoxSidebar}}的代码，这是宏调用。目前还没有太多文档，但这些宏来自KumaScript in Yari。
还需要记住其他一些事情。当您遇到错误时，在花大量时间试图了解问题到底是什么或如何解决它之前，请执行以下操作
- 在`content`存储库中查找同一页面，并确保页面仍然存在。如果它从`content`存储库中删除，您也可以安全地从`translated-content`中删除它。
- 查看已转换的另一种语言中的同一页面，看看他们是如何解决问题的。
例如，我遇到一个错误，我加载的页面只是在浏览器中打印了以下内容：`Error: 500 on /es/docs/Mozilla/Firefox/Releases/2/Adding_feed_readers_to_Firefox/index.json: SyntaxError: Expected "u" or ["bfnrt\\\\/] but "_" found.`。我把它缩小到 Markdown 中的以下代码片段
{{ languages( { "en": "en/Adding\\_feed\\_readers\\_to\\_Firefox", "ja": "ja/Adding\\_feed\\_readers\\_to\\_Firefox", "zh-tw": "zh\\_tw/\\u65b0\\u589e\\u6d88\\u606f\\u4f86\\u6e90\\u95b1\\u8b80\\u5de5\\u5177" } ) }}在法语中，他们似乎删除了页面，但是当我查看`zh-tw`时，看起来他们只是删除了这个宏调用。我选择了后者，只是删除了宏调用。这解决了问题，页面正确呈现。完成所有转换的文件后，就可以打开拉取请求了。
准备并打开拉取请求
# the dot says add everything
git add .首先准备好所有要提交的更改
如果您现在运行`git status`，您将看到以下内容
❯ git status
On branch 8192-chore-es-convert-firefox-release-docs-to-markdown
Changes to be committed: # this be followed by a list of files that has been added, ready for commit
提交您的更改
git commit -m 'chore: convert Firefox release docs to markdown for Spanish'
最后，您需要将更改推送到 GitHub，以便我们可以打开拉取请求
git push origin 8192-chore-es-convert-firefox-release-docs-to-markdown
您现在可以前往GitHub 上的翻译内容存储库，您应该会看到一个横幅询问您是否要打开拉取请求。单击“比较和拉取按钮”，并在下一页查看您的更改，以确保没有任何意外情况。
此时，您还可以在描述框中添加有关拉取请求的更多信息和上下文。同样重要的是，您需要添加以下行：“Fix #8192”。用您之前创建的问题的编号替换编号。我们这样做的原因是为了将问题和拉取请求链接起来。另外，拉取请求合并后，GitHub 会自动关闭问题。
对更改和描述感到满意后，请继续单击按钮打开拉取请求。在此阶段，GitHub 会自动分配来自适当本地化团队的某个人来审查您的拉取请求。现在您可以坐下来等待反馈。收到反馈后，解决审阅者要求的任何更改，并更新您的拉取请求。
当您都对最终结果感到满意时，拉取请求将被合并，您将帮助我们更接近 100% 的 Markdown。谢谢！不过，还剩下最后一步。打开电子表格，并使用拉取请求链接更新相关的行，并将状态更新为“正在审阅”。
拉取请求合并后，请记住返回并将状态更新为已完成。
如果您需要帮助，请与我们联系
如果您遇到任何问题并有疑问，请加入我们的 MDN Web Docs Matrix 频道。
https://matrix.to/#/#mdn:mozilla.org
照片由 Cristian Grecu 在 Unsplash 上提供
关于 Schalk Neethling
我是一名 Mozilla 人，一个热心肠的传道者、作家和开发者，对开源、网络标准和可访问性充满热情。我一直沉浸在这些世界中，以至于我觉得它们已经成为我的一部分，无法预见未来这些主题不会成为我日常生活的一部分。