alex

<h1 align="center"> <img width="300" src="https://yellow-cdn.veclightyear.com/87312a0a/c0ba1348-5e45-467e-80fa-6863f9b12e66.svg?sanitize=true" alt="alex"> <br> <br> </h1> > 📝 **alex** — 捕捉不敏感、不体贴的写作。 [![构建][build-badge]][build] [![覆盖率][coverage-badge]][coverage] [![首次贡献者友好][first-timers-badge]][first-timers] 无论是你自己的还是他人的写作，**alex** 都能帮助你发现偏向性别、极端化、涉及种族或其他**不平等**的措辞。例如，当出现"We've confirmed his identity"时，**alex** 会提醒你，并建议使用"their"来代替"his"。在[在线演示 »][demo]上体验 **alex**。 ## 为什么选择

有助于提高体贴性写作能力
捕捉许多可能的冒犯表述
提供有用的替代建议
可读取纯文本、HTML、MDX或markdown作为输入
风格优雅

安装

使用 npm（配合 Node.js）：

$ npm install alex --global

使用 yarn：

$ yarn global add alex

或者你可以按照这个步骤教程进行操作：在你的项目中设置 alex

检查项目

alex 检查以下内容：

带性别倾向的职业头衔（如果你写"垃圾男"，alex 会建议用"垃圾收集员"；如果你写"房东"，alex 会建议用"业主"）
带性别倾向的谚语（如果你写"像个男人一样"，alex 会建议用"勇敢地"；如果你写"淑女般的"，alex 会建议用"有礼貌的"）
歧视残疾人的语言（如果你写"学习障碍"，alex 会建议用"有学习障碍的人"）
居高临下的语言（如果你写"显然"或"众所周知"，alex 会对此发出警告）
不宽容的措辞（如果你写"主人"和"奴隶"，alex 会建议用"主要"和"副本"）
亵渎语（如果你写"屁股"🍑，alex 会对此发出警告） ……还有更多！

注意：alex 假定你的意图是善意的：你并不是有意冒犯他人！

查看 retext-equality 和 retext-profanities 了解所有规则。

alex 会忽略字面意义上的词语，所以 "他"、他 — ……，以及类似用法不会被警告。

集成

Sublime — sindresorhus/SublimeLinter-contrib-alex
Gulp — dustinspecker/gulp-alex
Slack — keoghpe/alex-slack
Ember — yohanmishkin/ember-cli-alex
Probot — swinton/linter-alex
GitHub Actions — brown-ccv/alex-recommends
GitHub Actions（reviewdog） — reviewdog/action-alex
Vim — w0rp/ale
浏览器扩展 — skn0tt/alex-browser-extension
Contentful — stefanjudis/alex-js-contentful-ui-extension
Figma — nickradford/figma-plugin-alex
VSCode — tlahmann/vscode-alex

忽略文件

CLI 在给定目录时会搜索带有 markdown 或文本扩展名的文件（因此 $ alex . 会找到 readme.md 和 path/to/file.txt）。要防止文件被发现，请创建一个 .alexignore 文件。

`.alexignore`

CLI 有时会搜索文件。要防止文件被发现，请在当前工作目录（即运行 alex 的位置）上方的某个目录中添加一个名为 .alexignore 的文件。这些文件的格式类似于 .eslintignore（而后者又类似于 .gitignore 文件）。

例如，当在 ~/path/to/place 中工作时，忽略文件可以位于 to、place 或 ~ 中。

本项目自身的忽略文件看起来像这样：

# `node_modules` 默认被忽略。
example.md

控制

有时alex会出错：

这句话会弹出一条消息。

结果如下：

readme.md
1:15-1:18  警告  `pop` 可能有歧义，请改用 `parent`  dad-mom  retext-equality

⚠ 1 个警告

可以使用 Markdown 中的 HTML 注释来忽略它们：

<!--alex ignore dad-mom-->

这句话将**不会**弹出消息。

结果如下：

readme.md: 未发现问题

ignore 会关闭注释后面内容的消息（在这个例子中是该段落）。也可以使用 disable 在注释后关闭消息，然后使用 enable 重新开启这些消息：

<!--alex disable dad-mom-->

这句话将**不会**弹出消息。

这句话也**不会**弹出消息。

再来一句话，同样**不会**弹出消息。

<!--alex enable dad-mom-->

这句话会弹出消息。

结果如下：

readme.md
9:15-9:18  警告  `pop` 可能有歧义，请改用 `parent`  dad-mom  retext-equality

⚠ 1 个警告

可以一次控制多个消息：

<!--alex disable he-her his-hers dad-mom-->

…通过省略所有规则标识符，可以控制所有消息：

<!--alex ignore-->

配置

您可以通过 .alexrc 配置文件控制 alex：

{
"allow": ["boogeyman-boogeywoman"]
}

…如果文件名为 .alexrc.yml 或 .alexrc.yaml，您可以使用 YAML：

allow:
- dad-mom

…如果文件名为 .alexrc.js，您还可以使用 JavaScript：

// 但像这样随机设置是个坏主意！
exports.profanitySureness = Math.floor(Math.random() * 3)

…最后，还可以在 package.json 中使用 alex 字段：

{
…
"alex": {
"noBinary": true
},
…
}

allow 字段应为规则数组或 undefined（默认为 undefined）。提供时，将跳过并不报告指定的规则。 deny 字段应为规则数组或 undefined（默认为 undefined）。提供时，仅报告指定的规则。不能同时使用 allow 和 deny。 noBinary 字段应为布尔值（默认为 false）。开启（true）时，像 he and she 和 garbageman or garbagewoman 这样的配对将被视为错误。关闭（false，默认）时，这样的配对是可以的。 profanitySureness 字段是一个数字（默认为 0）。我们使用 cuss，它有一个词典，对单词或短语作为亵渎语的可能性（而非其"糟糕"程度）进行 0 到 2 的评级：

评级	作为亵渎语使用	在干净文本中使用	示例
2	可能	不太可能	`asshat`
1	可能	可能	`addict`
0	不太可能	可能	`beaver`
`profanitySureness` 字段是您想要检查的最低评级（包含该评级）。
如果您将其设置为 `1`（可能），那么它会对级别 `1` 和 `2`（可能）的亵渎语发出警告，但不会对级别 `0`（不太可能）的发出警告。

CLI

![][截图]

假设example.md内容如下：

妖怪将所有更改写入**主服务器**。因此，从服务器是主服务器的只读副本。不过别担心，他是个残疾人。

现在，在example.md上运行alex：

$ alex example.md

输出结果：

example.md
1:5-1:14  警告  `boogeyman`可能有冒犯性，请使用`boogeymonster`代替                boogeyman-boogeywoman  retext-equality
1:42-1:48  警告  `master` / `slaves`可能有冒犯性，请使用`primary` / `replica`代替  master-slave           retext-equality
1:69-1:75  警告  不要使用`slaves`，这是亵渎性词语                                   slaves                 retext-profanities
2:52-2:54  警告  `he`可能有冒犯性，请使用`they`、`it`代替                          he-she                 retext-equality
2:61-2:68  警告  `cripple`可能有冒犯性，请使用`person with a limp`代替             gimp                   retext-equality

⚠ 5 个警告

使用$ alex --help获取更多信息。

当没有给alex输入文件时，它会在当前目录、doc和docs中搜索文件。如果给定--mdx参数，它会搜索mdx扩展名的文件。如果给定--html参数，它会搜索htm和html扩展名的文件。否则，它会搜索txt、text、md、mkd、mkdn、mkdown、ron和markdown扩展名的文件。

API

本包是仅支持 ESM的: 需要 Node 14+ 版本才能使用，且必须通过 import 而不是 require 来引入。

npm:

$ npm install alex --save

本包导出了标识符 markdown、mdx、html 和 text。默认导出为 markdown。

`markdown(value, config)`

检查 Markdown（忽略语法）。

参数

value (VFile 或 string) — Markdown 文档
config (Object，可选) — 参见[配置][]部分

返回值

VFile。

你可能对其 messages 属性感兴趣，如下例所示，因为它包含了可能的违规信息。

示例

import alex from 'alex'

alex('We've confirmed his identity.').messages

输出:

[
  {
    message: '`his` 在指代人时可能不够敏感，请使用 `their`、`theirs`、`them` 替代',
    name: '1:17-1:20',
    reason: '`his` 在指代人时可能不够敏感，请使用 `their`、`theirs`、`them` 替代',
    line: 1,
    column: 17,
    location: { start: [Object], end: [Object] },
    source: 'retext-equality',
    ruleId: 'her-him',
    fatal: false,
    actual: 'his',
    expected: [ 'their', 'theirs', 'them' ]
  }
]

`mdx(value, config)`

检查 MDX（忽略语法）。

注意：alex 使用的是目前处于 beta 阶段的 MDX@2 语法。

参数

value (VFile 或 string) — MDX 文档
config (Object，可选) — 参见[配置][]部分

返回值

VFile。

示例

import {mdx} from 'alex'

mdx('<Component>He walked to class.</Component>').messages

输出:

[
  {
    reason: '`He` 可能不够敏感，请使用 `They`、`It` 替代',
    line: 1,
    column: 12,
    location: { start: [Object], end: [Object] },
    source: 'retext-equality',
    ruleId: 'he-she',
    fatal: false,
    actual: 'He',
    expected: [ 'They', 'It' ]
  }
]

`html(value, config)`

检查 HTML（忽略语法）。

参数

value (VFile 或 string) — HTML 文档
config (Object，可选) — 参见[配置][]部分

返回值

VFile。

示例

import {html} from 'alex'

html('<p class="black">He walked to class.</p>').messages

输出:

[
  {
    message: '`He` 可能不够敏感，请使用 `They`、`It` 替代',
    name: '1:18-1:20',
    reason: '`He` 可能不够敏感，请使用 `They`、`It` 替代',
    line: 1,
    column: 18,
    location: { start: [Object], end: [Object] },
    source: 'retext-equality',
    ruleId: 'he-she',
    fatal: false,
    actual: 'He',
    expected: [ 'They', 'It' ]
  }
]

`text(value, config)`

检查纯文本（包括语法检查）。

参数

value (VFile 或 string) — 文本文档
config (Object，可选) — 参见[配置][]部分

返回值

VFile。

示例

import {markdown, text} from 'alex'

markdown('The `boogeyman`.').messages // => []

text('The `boogeyman`.').messages

输出:

[
  {
    message: '`boogeyman` 可能不够敏感，请使用 `boogeymonster` 替代',
    name: '1:6-1:15',
    reason: '`boogeyman` 可能不够敏感，请使用 `boogeymonster` 替代',
    line: 1,
    column: 6,
    location: Position { start: [Object], end: [Object] },
    source: 'retext-equality',
    ruleId: 'boogeyman-boogeywoman',
    fatal: false,
    actual: 'boogeyman',
    expected: [ 'boogeymonster' ]
  }
]

工作流程

建议的工作流程是将 alex 添加到 package.json 中，并在 Travis 中与您的测试一起运行。

您可以通过 alexrc 文件和控制注释来选择忽略警告。

一个使用 npm scripts 的 package.json 文件，并额外使用 AVA 进行单元测试，可能如下所示：

{
  "scripts": {
    "test-api": "ava",
    "test-doc": "alex",
    "test": "npm run test-api && npm run test-doc"
  },
  "devDependencies": {
    "alex": "^1.0.0",
    "ava": "^0.1.0"
  }
}