xenforo-markdown

English | 简体中文

Tip

欢迎贡献！请查看贡献一节。重构 work in progress，详见 https://github.com/McShare/xenforo-markdown/tree/v1.2

xenforo-markdown 是 XenForo 论坛 Markdown 支持的一个替代方案。它并不依赖 XenForo 本身，只是通过控制元素的内容（比如把元素的原本内容换成解析后的内容）来实现对 Markdown 预览和显示的支持。目前只会影响发布主题和更新主题两个操作。

本项目所用到的 Markdown 解析库为 markdown-it。在 v1.1.0 之前，使用的是 Showdown（现已不再维护）。

对 XenForo 的要求

要使脚本正常工作，你的 XenForo 上对内容的呈现方式必须与脚本实现的逻辑相匹配。

比如说，脚本会自动把带有 bbWrapper 这个类的元素里的文本转换成 HTML 替换上去，而如果你的 XenForo 在这方面表现得不一样，比如这个 bbWrapper 在你的论坛上面不叫 bbWrapper 而是 textWrapper、wrapper 之类的话，脚本将不能正常工作。通常情况下的 XenForo 是与脚本相匹配的（因为写脚本也是以当前 XenForo 为参考的），除非有一些特别大的更新或者用上了对这方面有影响的主题。如果类名等不匹配，你可能需要手动修改脚本中相应的内容。

用法

在正式开始使用 xenforo-markdown 之前，建议阅读注意事项，确保一切符合你的预期。

下面简单介绍了基本的安装方法，本质上就是让页面总是加载该脚本。

1. 从 Actions 处下载最新的构建后解压，将所需的文件放到一个可以用直链访问的地方。
2. 前往后台里的 外观 > 风格 & 模板 > 模板列表 搜索 PAGE_CONTAINER 模板打开。
3. 把下面的内容修改后复制粘贴到模板中的某个位置。

<link rel="stylesheet" href="/path/to/markdown.min.css"/>
<script src="/path/to/xf-markdown.min.js"></script>

保存即可。

现在访问每个页面都会加载该脚本，不过脚本只会在地址中有 post-thread、threads/ 或者其它几个关键字（详见代码）的时候发挥作用，分别对应发帖和浏览帖子等页面。写 Markdown 的时候，把内容放在 BBCode 类似的这样一个标签 [MD][/MD] 里即可。

[MD]
# Hello World!

这是用 Markdown 写的，你可以在预览和实际的帖子中看到效果。
[/MD]
这里不是 Markdown，你可以在这里用 BBCode 和富文本。

需要注意的是 [MD][/MD] 里的内容会被看做是纯文本，所以它们的富文本效果会被忽略。

构建

使用 npm install 安装必要的依赖后，可以运行下面的指令完成构建

npm run build

运行后会在 dist 文件夹里生成以下文件：

• xf-markdown.min.js - 编译和压缩后的 JS 文件
• xf-markdown.min.css - 压缩后的 CSS 文件，由 markdown.less 编译而来

你也可以在 Action 页面下载到每次提交后自动构建的版本。

黑暗模式检测 dark-detection.js

现在黑暗模式越来越广泛了，xenforo-markdown 也为渲染出来的元素添加了黑暗模式下的外观。

要让元素呈现出黑暗模式的外观，容器元素（也就是一些网站上的 bbWrapper）上需要有一个 dark 类。dark-detection.js 会监听开关元素（网站上可能出现的“切换主题”、“黑暗模式”的按钮等），然后判断用户是进入了黑暗模式，还是从黑暗模式中退出，根据这一点来决定添加或者删除指定元素上的 dark 类。

这种方法本身就具有不兼容性。如果想让这些逻辑在你的网页上正确运行，你可能还需要做一些重写，比如修改目标元素的选择器。这种方法也并非唯一，你完全可以编写自己的代码来添加 dark 类。

优劣对比

优势

• 用起来写起来装起来都比较简单，因为不依靠任何 XenForo 的 API。
• 安装和卸载很容易而且没有残留。不过不建议在跟你的用户说可以用 Markdown 以后卸载，因为这样所有的 [MD][/MD] 内容都会变为纯文本。
• 全面 CommonMark 语法支持。详见 markdown-it

劣势

• 因为这是用 JS 写的所以对于一些较大的数据处理起来会比较卡。
• 只是在前端将内容获取、转换然后替换，并没有做到和后端一样直接返回消息到前端来。这种方法说实话不是很好，显得有些多余，而且还会有性能问题。
• 如果网络或者设备比较慢是会有一段时间看到 [MD][/MD] 里的内容的。如果你有解决的思路可以提 PR 或者 Issue。

贡献

欢迎帮助我们优化 xenforo-markdown 的表现，这包括但不仅限于

• 让 xenforo-markdown 更加通用
• 优化项目结构
• 提升鲁棒性
• 提升性能
• 修复 Bug

贡献流程：

• Fork 项目，做出修改
• 在本地进行测试，确保能正常运行。本地测试方法详见本地测试说明。
• 提出 PR

协议

MIT