文档格式约定
本文档采用 markdownlint 作为所有 Markdown 文件的格式化工具,格式规则存储于 .markdownlint.jsonc 文件中,原则上所有 Markdown 文件均需通过验证、没有任何错误或警告信息才能提交到存储库中。
推荐使用 Visual Studio Code 作为本文档的编辑器,并安装 .vscode/extensions.json
中推荐的拓展以获得最佳编辑体验。
标题格式
- 每个标题均由简短的几个字组成,向用户说明下一节内容的大致格式
- 除首个大标题外,所有标题均应在末尾带有一个空格分隔的
{#<ID>}
来指定一个合理的 URL slug - URL slug 应由若干翻译准确、能清晰体现标题内容的英文单词组成,中间用
-
隔开。若标题本身由英文组成,请提供一个全小写、由-
替换下划线的 slug
用语约定
对象 | 用语 |
---|---|
文档阅读者 | 您 |
本平台 | SakuraFrp |
计算机知识丰富的 Geek / 专业用户 | 高级用户 |
HTTP 或 HTTPS 隧道 | HTTP(S) 隧道 |
提供内网穿透的服务器 | 节点 |
用于演示的节点域名 | idea-leaper-1.natfrp.cloud 、idea-leaper-2.natfrp.cloud 等 |
用于演示的隧道名称 | ExampleTunnel1 、ExampleTunnel2 、SampleTunnel1 、SampleTunnel2 等 |
用于演示的节点 ID 和名称 | #233 一个神奇的节点 、#5 Demo Node |
用于演示的 TLD | example.com 、example.net 或其他 RFC2606 中规定的 TLD |
如果您发明了一个新名词,请注意在不同地方使用时保持其一致性。
符号约定
- 用
空格
而不是Tab
进行缩进,缩进请交给 markdownlint 处理 - 用
\n
进行换行,文件内通常不应出现\r
- 空行不能包含空白字符,应该为单纯的
\n\n
,请交给 markdownlint 处理 - 在没有特殊说明的地方均使用半角符号,如:
:
,.
,<
,>
,(
,)
。通常这些符号后面需要加上一个空格来确保间距合理 - 在文字段落中均采用
,
逗号,每句话结尾需添加。
句号,段末通常以。
或:
结尾 - 列表条目、
tip
/warning
/danger
等提示容器中的文本通常不以。
结尾
文件结构
- 将所有图片放置于和 Markdown 文件位于同一级的
_images
文件夹中 - 将所有视频放置于根目录
_videos
文件夹中,并使用![](@source/_videos/foo-bar.mp4)
的引用形式
设计元素
基本说明
本文档支持引入视频、音频并展示播放组件,引入方式和图片一样,采用 ![](./_videos/example.mp4)
的形式。
本文档启用了 Markdown Enhance 插件的 选项卡、 属性支持、 脚注 和 导入文件 模块。
本文档启用了 VuePress 默认主题的 内置组件 和 自定义容器 支持。
此外,本文档还有其他自己实现的功能和自定义 CSS 类,例如 并排显示,请切换到其他标签查看。
并排显示
需要并排显示两块内容(较为常用的场景是并排展示代码块)时,请使用 natfrp-side-by-side
类,示例如下:
<div class="natfrp-side-by-side"><div>
```javascript
console.info('114514')
```
</div><div>
```javascript
console.info('1919')
```
</div></div>
展现效果:
console.info('114514')
console.info('1919')
文本间距
在正常文本和半角标点之间应添加空格,半角标点和全角标点之间无需空格:
文本文本 `修饰块` 文本文本 **修饰块** 文本
^ 空格 ^ 空格 ^ 空格 ^ 空格
文本文本 `修饰块`,文本文本 (文本文本) 文本
^ 空格 ^ 空格 ^ 空格
文本文本。`修饰块`、文本文本
^ 半角、全角标点之间无需空格
文本修饰
注意
markdownlint 被配置为不自动修复粗体或斜体的修饰字符,请注意遵守下方规则
使用 *
添加粗体、斜体效果:
*斜体*
**粗体**
***粗斜体***
如果需要添加一条 *
开头的斜体提示,可以使用 _
包裹 *
:
_* 这是一条温馨提示_
链接格式
- 在链接到文档内部元素时,请使用
/
开头的绝对路径链接,并确保链接中包含了文件扩展名.md
例:![prprrpr](/pa47.md)
- 在链接到外部站点时,请清理链接中不必要的追踪参数
正确示例:![这是好的](https://www.bilibili.com/video/BV1va411w7aM/)
错误示例:![这很不好](https://www.bilibili.com/video/BV1va411w7aM/?share_source=xxx&yyy=zzz)
无序列表
使用 -
作为列表标记,标记后添加一个空格:
- ItemA
- ItemB
有序列表
使用 1.
作为列表标记,也可以按个人喜好用 1.
、2.
、3.
等进行标记,只要保持整个文件一致即可。
标记后添加一个空格与内容分开:
1. ItemA
1. ItemB
1. ItemC