为 Marked 做贡献

¥Contributing to Marked

• 分叉 markedjs/marked。

  ¥Fork markedjs/marked.

• 使用 GitHub Desktop 或命令行在本地克隆库。

  ¥Clone the library locally using GitHub Desktop or the command line.

• 确保你在 master 分支上。

  ¥Make sure you are on the master branch.

• 请务必运行 npm install 或 npm update。

  ¥Be sure to run npm install or npm update.

• 创建分支。

  ¥Create a branch.

• 更新 src 文件夹中的代码。（lib 文件夹用于自动编译代码）

  ¥Update code in src folder. (lib folder is for auto compiled code)

• 运行 npm run test:all，修复任何损坏的东西（对于 linting，你可以运行 npm run lint 让 linter 为你修复它们）。

  ¥Run npm run test:all, fix any broken things (for linting, you can run npm run lint to have the linter fix them for you).

• 运行 npm run build:reset 以删除对编译文件的更改。

  ¥Run npm run build:reset to remove changes to compiled files.

• 提交拉取请求。

  ¥Submit a Pull Request.

设计原则

Marked 倾向于遵循 SOLID 软件设计和开发原则集；主要是 单一责任 和 开放/封闭原则：

¥Marked tends to favor following the SOLID set of software design and development principles; mainly the single responsibility and open/closed principles:

• 单一责任：Marked 及其组件负责将 Markdown 字符串转换为 HTML。

  ¥Single responsibility: Marked, and the components of Marked, have the single responsibility of converting Markdown strings into HTML.

• 打开/关闭：Marked 倾向于为开发者提供轻松扩展库及其组件的方法，而不是通过配置选项更改 Marked 的行为。

  ¥Open/closed: Marked favors giving developers the means to easily extend the library and its components over changing Marked's behavior through configuration options.

优先级

我们认为我们已经对构建质量的优先级进行了排序。

¥We think we have our priorities sorted to build quality in.

下表列出了我们在通过问题或 PR 对代码进行工作时使用的票证类型标签；按优先顺序。

¥The following table lists the ticket type labels we use when there is work to be done on the code either through an Issue or a PR; in priority order.

票证类型标签	说明
L0 - security	发现 Marked 库中的安全漏洞。
L1 - broken	与 支持的规范 相比，有效使用会导致输出不正确或导致标记崩溃，并且没有已知的解决方法。
L2 - annoying	与 L1 类似 - 只损坏了，有一个已知的解决方法可用于解决该问题。
RR - 重构和重新设计	结果对使用 Marked 的开发者（可读性提高）或终端用户（性能更快）或两者均有改善。
NFS - 新功能（与规范相关）	Marked 目前不提供的功能，但属于 支持的规范 之一
NFU - 新功能（用户请求）	Marked 目前不提供的功能，但 Marked 用户已请求提供。
NFE - 新功能（应该是扩展）	Marked 目前不提供的功能，也不是规范的一部分。

尽早、经常、全面地进行测试

我们尝试编写测试用例来验证输出（基于 支持的规范 编写测试）并尽量减少回归（为已修复的问题编写测试）。因此，如果你想做出贡献，你应该了解有关测试工具的一些信息。

¥We try to write test cases to validate output (writing tests based on the supported specifications) and minimize regression (writing tests for issues fixed). Therefore, if you would like to contribute, some things you should know regarding the test harness.

位置	说明
/test/specs/commonmark	测试 CommonMark 合规性
/test/specs/gfm	测试 GFM 合规性
/test/specs/new	与原始 markdown.pl 无关的测试。
/test/specs/original	针对原始 markdown.pl 进行验证的测试。
/test/specs/redos	测试 ReDOS 漏洞

如果你的测试使用功能或选项，例如假设 gfm 设置为 false，你可以将 front-matter 添加到 .md 文件的顶部

¥If your test uses features or options, assuming gfm is set to false, for example, you can add front-matter to the top of your .md file

---
gfm: false
---

提交 PR 和问题

¥Submitting PRs and Issues

Marked 提供提交拉取请求和问题的模板。当你开始创建新的 PR 或问题时，你将看到有关使用模板的说明。

¥Marked provides templates for submitting both pull requests and issues. When you begin creating a new PR or issue, you will see instructions on using the template.

PR 模板包括提交者和审阅者的清单，在大多数情况下，他们不是同一个人。

¥The PR templates include checklists for both the submitter and the reviewer, which, in most cases, will not be the same person.

脚本

¥Scripts

对于 NPM 命令，我们尝试使用 NPM 框架提供的原生脚本。

¥When it comes to NPM commands, we try to use the native scripts provided by the NPM framework.

运行测试：

¥To run the tests:

npm test

要测试你是否正在使用项目的标准语法规则：

¥To test whether you are using the standard syntax rules for the project:

npm run test:lint

要查看 Marked 与其他流行 Markdown 库之间的时间比较：

¥To see time comparisons between Marked and other popular Markdown libraries:

npm run bench

要查看 src/rules.js 中的编译规则：

¥To see the compiled rules from src/rules.js:

npm run rules

你可以指定一个或多个 rule path 以仅显示某些规则：

¥You can specify one or more rule paths to only show certain rules:

npm run rules -- block.gfm.item inline.pedantic.br

{
  block: {
    gfm: {
      item: /^( *)((?:[*+-]|\\d{1,9}\\.)) ?[^\\n]*(?:\\n(?!\\1(?:[*+-]|\\d{1,9}\\.) ?)[^\\n]*)*/gm
    }
  },
  inline: {
    pedantic: {
      br: /^( {2,}|\\\\)\\n(?!\\s*$)/
    }
  }
}

要检查（并修复）标准化语法（lint）：

¥To check for (and fix) standardized syntax (lint):

npm run lint

要构建你自己的 es5、esm 和最小化版本的 Marked：

¥To build your own es5, esm, and minified versions of Marked:

npm run build