PKMer 文档写作规范-论坛话题规范

PKMer
1

PKMer 论坛中的帖子，会定期被社区贡献者、或者社区用户，以人工选择，或者投票，个人推荐方式，推荐到 PKMer 社区进行审核，大家可以理解为加精华。

被加精华帖子，会以文章的形式展示在 pkmer 知识社区网站，作者对应 id 会作为作者id

鉴于网站会涉及到 SEO ，以及保证网站和论坛需要具有一定永兴，需要保证文档的规范性和可读性，将规范文档的使用语法和格式，以带给读者最佳的阅读体验。

文档内容规范

  1. 遵纪守法：所有内容必须符合国家、社会价值观以及相关互联网内容的法律法规。
  2. 不涉及价值判断：避免在您的内容中明确的价值判断和主观性言论。保持客观和中立，以事实和信息为基础，让读者自行评估。禁止通过贬低或者批评别人来行文。
  3. 避免敏感议题：尽量避免直接涉及政治、军事等敏感议题。这些议题容易引发争议和纷争，可能对社区的运作和口碑造成不利影响。
  4. 拒绝夸大言论：确保避免使用过度夸张和极端的措辞，如过度吹捧或贬低。保持内容的客观、理性和平衡。
  5. 不插入无关链接：避免在内容中插入无关的知识链接。这样的链接可能会对整体的 SEO（搜索引擎优化）和社区的运作产生不利影响。
  6. 不允许在社区文章中引战，包括指名道姓的批判某人或者某次事件。
  7. 不商业化导向：避免在内容中有明显的商业化指向。保持内容的纯粹性和客观性，避免过分的商业推广和广告性内容。如果内容是引导消费、广告或广告嫌疑，或者为了其他插件、软件后续收费做推广，那么为了社区良好的发展，请先联系管理员，告知你的意图。

文档格式规范

文档规范有三个：

  1. 话题名称：
  2. 会被作为文章标题的首选，所以如果有加精的需求，请慎重理。当然这些标题后续也是可更改的
  3. 文档语法规范：除了本文的语法规范
  4. Obsidian 社区插件的协作可以参考 [[obsidian-textgenerator-plugin]] 提供的示例，须在一级标题下放置说明卡片，介绍基本功能，介绍基本用法后，方可随意发挥。
  5. 其他文章或者活用内容，长文需要考虑拆分系列问题，如果引用多个插件或者内容，尽可能确保引用的 MOC 有内容，不会出现死链

文档语法规范

[!Warning] 特别声明
如你是搬运或者翻译，那么请要获得原作者许可，已经提供我们原文链接

标题语法

  • 一级标题为你的论坛话题标题，对应我们上网时候的文章标题和网页标题
    • 以前的文档都规定一篇文章只有一个 h1 标题，所以为了保证兼容其它发布工具，我们也采取这个规范。
  • 正文以二级标题开始
  • 文档内容从二级标题开始，文档内不超过 4-5 级标题。这是出于对 SEO 优化所制定的规范
  • 只使用 # 语法表示标题。理论上 —，=都可用来表示标题，但不建议这样做。
  • 标题不应含有特殊字符：如 latex 公式，代码块，数字编号等
  • 标题前后要有空行

无序列表和有序列表

  • 列表不应该混用：Obsidian 的某些限制，在嵌套列表语法时会导致排版错乱，不建议混用。
  • 仅使用 - 作为无序列表标记：

文字及样式

  • 加粗：** **
  • 斜体：* *，不使用下划线的写法
  • 高亮：== == 这尽管不是通用 md 语法，但在各大平台有兼容 ==高亮==
  • 删除线：~~ ~~ 删除
  • 行内代码：` 使用反引号
  • 引用：>
  • 表格：Github 风格的表格，即 Obsidian 支持的表格
  • callout：兼容Obsidian 内置的几种 callout 语法
  • 代码块：使用默认三反引号语法
  • 脚注：仅支持 [^1] 风格的脚注，脚注内容须放到文章末尾，以 [^1]: footnote 的形式呈现。
  • 除上述文字样式外，不使用 html 语法改变文字样式，仅在特殊情况下使用 html 语法增添文档的趣味性。

链接

  • 不使用死链作为你的文章中的链接
  • 不为外部付费内容引流，防止出现社区口碑问题
  • 不要使用他人钓鱼链接或者你不确定安全性的链接

图片

  • 论坛会自动将内容，放到 pkmer 图床，无需你另外寻找。
  • 使用 ![[]] 的语法
  • 格式：尽量使用 png，jpg，gif 这三种格式的图片和动图。

视频

  • 不支持插入本地视频
  • 支持插入网页视频，通过 iframe 标签语法引用 B 站视频，通过 ![[]] 引用远程地址视频。
<iframe src="https://player.bilibili.com/player.html?aid=702374093&bvid=BV1Xm4y1n7bQ&cid=1232824646&page=1&autoplay=false" scrolling="no" border="0" frameborder="no" framespacing="0" allowfullscreen="true" width="80%" height="500"> </iframe>

以 B 站为例子，注意需要增加 &autoplay=false，需要增加 width="80%" height="500"

正文

  • 正文内不使用 html 标签
  • 中英文间隔一个空格
  • 中文和数字间隔一个空格
  • 大小写：尽量别简写，专有名词首字母大小写，且符合缩写规律。如：Obsidian 需要一位熟悉 JavaScript、HTML5，至少理解一种框架（如 Backbone.js、AngularJS、React 等）的前端开发者。
  • 标点符号：中英文段落中标点符号不混用。末尾是否有标点不要求。
  • 专有名词适当保持英文