未格式化代码检测器

[Discourse]

	摘要	未格式化代码检测器 会检测未格式化的代码，并在发布前发出警告。
	预览	在 Discourse 主题创建器中预览
	仓库链接	https://github.com/discourse/unformatted-code-detector
	初次接触 Discourse 主题？	Discourse 主题使用入门指南

安装此主题组件

由于这是由 Discourse 团队维护的#官方主题组件，因此可以在 Meta 的相应类别中提出#支持、#Bug、ux 和#功能请求，并打上适当的主题组件标签。点击下方的链接即可开始。:+:1:

 支持  Bug  UX  功能

功能

发布未格式化代码的用户将看到一条警告消息，指导他们如何正确格式化代码。

灵敏度和是否检测 HTML 可通过主题设置进行配置。

设置

名称	描述
emoji icon	在未格式化警告模态框标题旁边显示的 emoji 图标。
disable at trust level	禁止对信任等级为 N 或更高的用户显示警告。-1 = 对所有用户启用。
sensitivity	检测算法的灵敏度。0 = 插件已禁用；1 = 对任何看起来略微像代码的内容发出警告。
min post length to check	要检查的最小帖子长度（字符数）
max post length to check	要检查的最大帖子长度（字符数）。-1 = 无上限。
include html	检查 HTML 标签以及其他类型的代码。如果用户经常需要在帖子中渲染自定义 HTML，建议禁用此项。

翻译键	默认值
warning_modal.title	您正在发布代码吗？
warning_modal.content	您的帖子似乎包含代码或日志。为了保持帖子的可读性，请记得使用预格式化文本工具栏按钮 或键盘上的反引号 ` 键来格式化您的代码，示例如下：[examples]
warning_modal.do_not_show_again	不再显示此消息
warning_modal.fix_post	编辑帖子
warning_modal.ignore_and_post_anyway	无论如何都要发布

调试

如果您收到针对不包含任何文本的帖子的警告，可以通过打开浏览器 JS 控制台并输入 debugUnformattedCodeDetector() Enter 来打印调试信息。这将打印有关哪些行被视为“代码”以及灵敏度设置的信息。

“不再显示此消息”仅按设备生效，不按用户生效。这是一个已知问题，一旦 Discourse 获得将用户信息附加到主题的功能，该问题将被修复。

由我们托管？ 主题组件可在我们的标准版、商业版和企业版计划中使用。

[robbiet480 (Robbie Trencheny)]

We at the Home Assistant forums think that this is the best thing invented since sliced bread. Or maybe Home Assistant. Thank you so so much @lionel-rowe!!!

Two minor request:

• I don’t want to allow users to skip formatting or disable the dialog in the future. I want them to feel pain until they change their ways. I’m sadistic like that. Can you make the “Don’t show this message again” and “Post anyway” buttons optional? For now I’ve hid them with some CSS but would be better to just not include the HTML at all.

• Unsure if you are doing language detection or not, but if you are, can you add the estimated language name after the first code fence so that users will properly syntax highlight too?

Thanks so much!!

[lionel-rowe]

@robbiet480

I don’t want to allow users to skip formatting or disable the dialog in the future. I want them to feel pain until they change their ways. I’m sadistic like that. Can you make the “Don’t show this message again” and “Post anyway” buttons optional? For now I’ve hid them with some CSS but would be better to just not include the HTML at all.

I wouldn’t recommend hiding them, especially if you leave the setting to include HTML detection on. Power users may still want to have their (sanitized) HTML parsed as such, not formatted as code. Two examples where this can be useful are kbd and abbr tags.

If you exclude HTML tags from detection (which may be viable depending on the scope of your forum), hiding the “don’t show this again” would probably be OK. I still wouldn’t recommend hiding the “post anyway”, though, because there are bound to still be some edge cases of false positives (I hit one the other day where I’d omitted a space before an opening parenthesis — poor typesetting, but not unformatted code). Then you’ll have a situation where users can’t post their question at all, and, unless they report the issue to you directly, you won’t even know about it.

@robbiet480

Unsure if you are doing language detection or not, but if you are, can you add the estimated language name after the first code fence so that users will properly syntax highlight too?

Language detection is beyond the scope of this component, I’m afraid. Where possible, it looks for syntactical features shared by many languages, such as lines ending in semicolons, certain configurations of curly braces, and so on.

I am thinking about ways to enhance the UX, though. One big improvement would be to make it much more interactive. For example, instead of a simple modal, the user would be presented with a wizard that first asks them which language their post concerns (select from a dropdown), then a screen which asks them to select which ranges of their post are code (defaulting to lines that contain strings flagged by the plugin), then generating the appropriate markdown. This would still include a “skip and post anyway” option, though, for the reasons I mentioned.

I don’t have a timeline for this change, but it’d be good to know if it’s something people would be interested in.

[robbiet480 (Robbie Trencheny)]

Already hit the edge cases issue within 30 minutes or so of hiding the elements, so they have been re-added.

I would be super interested in the modal being more interactive!

[codinghorror (Jeff Atwood)]

简短说明：我们将很快正式推出该组件，并与 @lionel-rowe 和 @david 紧密合作以实现这一目标。如有任何想法或反馈，现在正是分享的好时机！

[tpetrov (Toni Petrov)]

@codinghorror

简要说明，我们很快将正式推出此组件，并将与 @lionel-rowe 和 @david 紧密合作以实现这一目标。有任何想法或反馈，现在正是分享的好时机！

真是个好消息！

不确定这是否合理，但如果能针对最常见的破坏格式化的 Markdown 错误发出警报，那就太棒了。

[tpetrov (Toni Petrov)]

如果能提示疑似未格式化代码的位置，那就更好了。

我刚才正在写另一条回复时收到了警报，尽管我并没有粘贴任何代码。过了一会儿我才意识到，是因为我使用了单词 topic_id……但在我看来，检测器认为这个词是代码这一点并不明显（大多数人也不会这么想）。

我认为，一个单词中包含下划线并不一定意味着它就是代码。

[lionel-rowe]

感谢大家至今为止的反馈！我们将添加并调整一些设置，以降低检测的过度敏感。

@tpetrov 还有另一件事——弹窗的措辞是否清楚表明，如果你认为自己的帖子不包含代码，可以选择忽略它并继续发布？还是说它让你觉得必须找到并“修复” perceived 的问题？

[tpetrov (Toni Petrov)]

我担心很多人不会仔细阅读……
如今，当人们看到包含多句话的弹窗时，似乎会直接忽略文字，转而寻找“确定”按钮（例如“我接受 Cookie、条款等”）。

不过，也许可以将“您的帖子似乎包含未格式化的代码”改为“您的帖子中是否包含代码？”，因为疑问句往往更能吸引注意力。

我并非用户体验专家，但这个按钮看起来有点过于强硬：
—— 这是我不太愿意点击的按钮。当然，这正是设计意图：让人们不会轻易跳过它，而是尝试更好地格式化自己的帖子。

[mbauman (Matt Bauman)]

哦，我喜欢这个想法……但我刚刚遇到了一个误报：

Discobot tutorial generating modmail

It’s still early for our relatively small site but this is looking promising. In the month prior to changing this, 18 folks did that tutorial step and 4 flagged it wrong. In the month+ since 17 have done that step and 0 got it wrong. The new text adds a few more details about why you might flag a post but I’m guessing it’s the very small change to the final sentence that’s doing most of the work: We like our discussions friendly, and we need your help to keep things civilized. If you see a…

会不会是那些损坏的链接触发了它？它们只是从模板引擎中提取的，看起来像 [keep things civilized](%{guidelines_url})。或者是 HTML 的 img 标签？

[lionel-rowe]

@tpetrov

不过，也许可以将“您的帖子似乎包含未格式化的代码”改为“您的帖子中是否包含代码？”，因为有时提问更能引起注意。

不错的主意，@david，或许我们可以尝试将弹窗标题改为“您正在发布代码片段吗？”

@tpetrov

我不是 UX 专家，但这个按钮看起来有点“核弹级”：
—— 这是我不太愿意点击的东西。当然，这正是设计的意图：让人们不会轻易跳过它，而是尝试更好地格式化他们的帖子。

我想你说得对。下一个版本中，该按钮将采用标准的灰色样式。

@mbauman

会不会是损坏的链接触发了它？这些链接直接来自模板引擎，看起来像：[保持文明](%{guidelines_url})。或者是 HTML 的 img 标签？

结果发现两者都有！下一个采用默认设置的版本将不再针对此帖子触发该提示。

[codinghorror (Jeff Atwood)]

我们正在推出新文案，并为该组件构建正负测试样本帖子的语料库。请耐心稍候，进展顺利！

[tmomas]

@codinghorror

有什么想法或反馈吗？现在是分享的时候了！

一个小细节：warning_modal.content 的默认内容要求的是“代码”工具栏按钮，但在编辑器中，当您将鼠标悬停在该按钮上时，它被称为“预格式化文本”按钮。

为了让新用户更容易找到该按钮（他们找不到任何“代码”按钮），应将 warning_modal.content 从“代码按钮”更改为“预格式化文本按钮”。

[tmomas]

如何向主题添加一个包含更多示例和说明的链接？

我尝试简单地将其添加到 warning_modal.content 的末尾，但结果如下（我的添加内容已用黄色标记）：

我该如何在当前内容下方添加一些文本和链接？

编辑：

我刚刚注意到，即使更改 warning_modal.content 中的单个字符也会破坏格式。

更糟糕的是：只需点击 warning_modal.content 输入框，然后使用箭头键移动光标，输入框就会高亮显示。点击绿色对勾保存“已编辑”的 warning_modal.content（实际上没有任何更改，只是将光标移动了一个字符）后，格式就会像上面所示那样被破坏。

编辑 #2

在 https://meta.stackexchange.com/questions/82718/how-do-i-escape-a-backtick-within-in-line-code-in-markdown 的帮助下已解决。

@codinghorror @lionel-rowe 也许你们应该研究一下这个问题，并相应地调整默认的 warning_modal.content，特别是关于空格和反引号的问题（在大量使用反引号的“多行”部分中缺失空格导致了上述问题）。

[tmomas]

有没有什么方法可以更明确地告知用户，如果手动添加代码围栏（即不通过按钮），应该选择哪个键？

今天我看到了这样的情况：

用户显然试图遵循说明，但为代码围栏选择了错误的键（使用了 ' 而不是 `）。过去我也见过使用 ... 而不是 ``` 的情况。这两种情况都表明，用户需要更明确的指导来选择正确的键。

另一种方案：不要用这些键让用户感到困惑，直接说明：使用“预格式化文本”按钮即可。

---

@lionel-rowe 我该如何自定义检测行为？

目前 shebang 未被识别为代码，我希望更改这一点。

预期行为：#! 表示脚本的开始，因此应被识别为代码。

未检测到的示例：

---

#!/bin/sh

echo “test”

. /lib/upgrade/common.sh

firmware=“/tmp/firmware.img”
tmpdir=“/tmp/_upgrade”
output=“/dev/ttyS0”
before=“before-upgrade.sh”
after=“after-upgrade.sh”

---

此外，对我们来说，如果能将 root@ 识别为代码也会很有用。

root@OpenWrt:~# ip link add link eth0 name eth0.9 type vlan id 9
root@OpenWrt:~# brctl addbr br-foo
root@OpenWrt:~# brctl addif br-foo eth0.9
root@OpenWrt:~# ip link set eth0.9 up
root@OpenWrt:~# ip link set br-foo up

[codinghorror (Jeff Atwood)]

@tmomas

除此之外，如果我们能检测到 root@ 为代码，那对我们来说会很有用。

@david 有办法自定义检测吗？

[david (David Taylor)]

目前无法实现按站点自定义，不过我们确实可以考虑在“代码能量”系统中添加 shebang 和 shell 提示符检测功能。

[david (David Taylor)]

@tmomas

只需点击 warning_modal.content 输入框，然后使用箭头键移动光标，该输入框就会被高亮显示。点击绿色对勾保存“已编辑”的 warning_modal.content（实际上并未做任何更改，只是将光标移动了一个字符）后，格式就会像上面显示的那样损坏。

感谢您提出这个问题——这看起来是一个关于多行主题翻译的核心错误。我已提交了一个拉取请求（PR）来修复此问题：

FIX: Use <textarea> for theme translations (#14322)

[hhlp]

大多数 Discourse 站点使用 Discourse 作为故障排查工具，此插件是否适用于以下任务（不仅限于代码）：

Linux：

• 日志
• Linux 命令行 CLI
• 终端输出

例如：

Sensors:
  System Temperatures: cpu: 78.0 C mobo: 36.0 C gpu: nouveau temp: 56.0 C 
  Fan Speeds (RPM): cpu: 0 fan-1: 3139 fan-3: 0 fan-5: 0 
  Power: 12v: N/A 5v: 2.90 3.3v: N/A vbat: 3.34 

此致，