PKMer 文档写作规范

PKMer 文档写作规范

鉴于需要保证文档的规范性和可读性,将规范文档的使用语法和格式,以带给读者最佳的阅读体验。

文档内容规范

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

文档格式规范

文档规范有三个:

  1. 文件和文件夹规范:
    1. 文件名应尽可能简短,最好不超过 12 个字符,不能包含特殊的字符比如空格,/$ ,为了网站显示正常,建议文件名只能包含:中英文、数字、短横线、下划线,网站实际显示的标题是文档 frontmatter 中的 title 字段,跟文件名无关。
    2. 除一级文件夹为了维持文件夹在 Obsidian 中的显示顺序外,子文件夹不需要再进行编码以保证显示顺序 (考虑到有索引文件,顺序的重要性降低了)。Obsidian 社区插件的写作,文件名必须用插件的 id,可以在插件文件夹的 manifest.json 文件中查看。
    3. 不要丢失你的作者信息
  2. 文档的 frontmatter 规范:用于方便检索和展示元数据。
  3. 文档语法规范:除了本文的语法规范
    1. Obsidian 社区插件的协作可以参考 obsidian-textgenerator-plugin 提供的示例,须在一级标题下放置说明卡片,介绍基本功能,介绍基本用法后,方可随意发挥。

文件和文件夹规范

文档的目录结构和说明如下:

Pkmer-Docs
├── 00-关于
├── 01-社区资源合集
├── 02-知识管理基础
├── 03-知识管理工具
├── 10-Obsidian
├── 20-深入理解知识管理
├── 30-知识管理具体应用
├── 40-开发者指南
|—— 90-其它
├── Config
│   └── QuickAdd
│       └── update-yaml-title.js
├── License
├── README.md
└── Resource
    └── Images
  • 编号以 0 开头的是基础内容和一些推荐阅读内容。比如了解本组织,资源合集,知识管理基础,笔记软件横评等内容。
  • 编号以 1 开头的是具体知识管理软件的使用
  • 编号以 2 开头的是知识管理进阶内容
  • 编号以 3 开头的是知识管理具体应用
  • 编号以 4 开头的是插件开发,脚本等内容
  • 编号以 9 开头的是其它内容,暂时不好分类或者偏离主题的内容
  • Config 文件夹放置本库的脚本,库内配置
  • Resource 文件夹放置本地图片,canvas,excalidraw 等其它非 md 资源

大致按照下述思路组织:

0 开头的文件夹内容是最基础的内容和一些资源工具类内容。进而是笔记软件的使用,建立在基础内容之上。紧接着是高级内容,阐述信息组织,信息管理等一些理论知识。最后是结合笔记软件和笔记方法,分享工作流和经验。扁平化组织,逐级递进。

Loading graph...

文件名

  • 文件名不要使用中文的标点符号
  • 遇到空格或者标题中需要加入冒号、逗号、顿号等,可以使用 - 来替换

文档 frontmatter 规范

文档 frontmatter 是自动生成的,可通过内置的 ctrl + s 快捷键在 Obsidian 内快速实现。

  • 如果你使用我们提供的库,下面内容是自动生成的
    1. uid:自动生成,文件的唯一定位标识符,也是文档创建的时间戳
    2. title:文件名,自动生成
    3. draft:用于标识是否发布
    4. editable:文章创作者是否允许修改
    5. modified:修改时间的时间戳
  • 这些需要手动完成
    1. author:英文逗号分割的作者名,后续修订者记得加上自己的笔名。加不加都会成为贡献者
    2. tags:标签,以 [tag1,tag2] 的格式呈现,文中的标签会自动更新到 yaml 中
    3. description:文件内容描述,用于网站展示内容和 SEO 优化
    4. type:文档类型,默认为 other。其余可选类型为:
      • tutorial——教程,除了需要知道电脑的基本知识外,完全不需要任何前置条件,手把手教会读者主题内容
      • basic——基础,用于学习一些核心概念,同时回答一些基础性问题。只有学习这些基础才能理解后续主题内容
      • advanced——进阶,进阶使用,包含高级玩法,奇技淫巧
      • practice——实践,介绍完整的工作流,查询手册
      • awesome——索引,MOC 索引页,资源收集等
      • other——其它:关于笔记的轶闻趣事等其它内容的分享

文件名

因为对应的文件会成为网页链接地址,所以文件中不能使用中文的 —,!@#:&

文档语法规范

特别声明

如你是搬运或者翻译,那么请要获得原作者许可,已经提供我们原文链接

标题语法

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

无序列表和有序列表

  • 列表不应该混用:Obsidian 的某些限制,在嵌套列表语法时会导致排版错乱,不建议混用。
  • 仅使用 - 作为无序列表标记:这可通过内置的 ctrl + s 快捷键在 Obsidian 内自动修正。
  • 自动修正编号:这可通过内置的 ctrl + s 快捷键在 Obsidian 内快速实现。

文字及样式

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

链接

  • 文档链接使用双链语法:链接在 README 文件中使用相对路径写法,除此之外使用双链语法。双链语法在 Obsidian 中简洁且优雅。
  • 网址使用 []() 语法

图片

  • 使用本地图片的方式:放置图片到 Resource/Images 内,不要求命名格式,后续我们统一处理。
  • 使用 ![[]] 的语法:除 README 外,其余各处使用优雅的 Obsidain 双括号语法。
  • 格式:尽量使用 pngjpggif 这三种格式的图片和动图。

提示

因为没有开放图床权限,对于管理员请注意:

  • 如果是插入链接图片,如 ![image.png](https://cdn.pkmer.cn/images/20231018143712.png!pkmer) 此形式。
  • 注意,需要修改 image.png 改为对应的标题名和图的名称

视频

  • 不支持插入本地视频
  • 支持插入网页视频,通过 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 标签
  • 中英文间隔:这可通过内置的 ctrl + s 快捷键在 Obsidian 内快速实现。
  • 中文和数字:这可通过内置的 ctrl + s 快捷键在 Obsidian 内快速实现。
  • 大小写:尽量别简写,专有名词首字母大小写,且符合缩写规律。如:Obsidian 需要一位熟悉 JavaScript、HTML5,至少理解一种框架(如 Backbone.js、AngularJS、React 等)的前端开发者。
  • 标点符号:中英文段落中标点符号不混用。末尾是否有标点不要求。
  • 专有名词适当保持英文:主要是考虑到 OB 自身汉化的完整度不高,而且有时候交流中,使用英文称呼更能精准传达意思

库内置插件和工具

注意

使用内置插件和工具需要您确保已手动打开插件

  • dataview:用于库的统计和追踪
  • obsidian-git:用于查看和可视化操作 git
  • obsidian-linter:规范和格式化 md 文档,按 ctrl + s 进行格式化,建议没事按着玩
  • qucikadd:自动化处理脚本,帮助处理一些繁琐内容,目前有快捷打开命令行,css 片段,script 文件夹,gvim,Vscode 和自动更新 frontmatter 的 title 字段的功能,ctrl + p 打开命令窗口选择对应的命令即可。
  • obsidian-advanced-table:快捷输入表格
  • obsidian-outliner:快捷操作无序列表
  • latex-suite:快捷输入 callout 等内容片段

对于其它您爱使用的插件和主题,请随意安装,由于有 .gitignore 文件,并不会影响到上游库的更改。

其中 latex-suite 内置两个自定义的片段:

  1. 输入 !note<tab> 则会拓展为 note callout 样式,note 可以是任意字符,比如 !tips<tab>
  2. 输入`mermaid 则会拓展为 mermaid 代码块

其它

如您需要其它帮助协作者开发的工具,可以在 Github 提交 Issue 联系我们开发,或者 PR 分享

讨论

若阁下有独到的见解或新颖的想法,诚邀您在文章下方留言,与大家共同探讨。



反馈交流

其他渠道

版权声明