NISA Wiki 编写规范¶

重点必看¶

尽可能不要移动文件的目录结构, 这个操作相当于删除文件后再新建, 会导致协作记录丢失

Markdown 规范¶

请先尽可能的学习 Markdown 的语法及规范, 熟练掌握文本编辑能力, Markdown 规范教程如下

https://markdown.com.cn/

Wiki 结构介绍¶

整体结构介绍¶

Text Only

\NISA-WIKI
|   .gitignore   # git 忽略的文件, 写入这里的文件, git 会忽略它(比如这里忽略了'.cache'缓存文件夹)
|   LICENSE   # 因为上传到了 github, 作为一个开源项目, 一个许可证是必不可少的, 这里选择了 CC4.0 协议
|   mkdocs.yml   # 本 Wiki 采用 Material for MkDocs 作为框架, 这个文件是该框架的配置文件
|   README.md   # 基本每个开源项目都会有该文件, 基本会写着项目的简介和使用
|   requestment.txt   # 本地预览前需要安装的Python依赖
\---.cache  # Material for MkDocs 启动本地预览时, 会生成的缓存文件
\---.github  # Github 相关的配置文件
|   \---workflows   # Github 自动化工作流配置文件放置的目录
|           ci.yml   # 比如这里就创建了一个工作流, 基本功能就是将最新同步的 Markdown 构建为 HTML 页面, 放置在 gh-pages 分支中
\---docs  # 这里存放着就是 Wiki 的正文了, 作为非运维用户, 你只需要修改这里面的内容就可以了, 下文在详细展开
    \--- 这里省略一堆文件夹
    \---assets  # 附件存放目录, 下文会介绍它的使用规范
    |       NISA_LOGO.svg
    \---javascripts  # 一些配置 Wiki 时需要用到的 js 文件, 非运维用户无需在意它们

Wiki 正文结构介绍¶

可以查看该协作指南的文件夹结构进行参考

顶部导航栏¶

顶部导航栏是根据 ./docs/ 目录下的第一层文件夹决定的, 文件夹名就是导航栏显示的名称

因为默认采用字典序排序, 所以这里使用数字前缀方便排序(本导航栏各子项顺序与属性无关)

左侧导航栏¶

进入 顶部导航栏的子项中, 就会在页面左侧看到一个该子项的更详细的导航栏

文件夹¶

这个导航栏也是由文件夹目录结构决定的, 并且每一层文件夹名会在导航栏中显示出来

并且排序它们的排序是由文件夹名的字典序进行排列, 如果需要自定义顺序可以采用 两位十进制数字-文件夹名 的形式命名文件夹

文件¶

不过如果是 Markdown 文件, 文件名一般情况下不会显示在导航栏中, 而是显示 Markdown 文件的一级标题, 如果没有一级标题的话, 才会显示文件名

但是 Markdown 文件名称却决定着导航栏的排列顺序, 所以如果要排序的话, 也是可以选择使用 两位十进制数字-文件名 的形式命名进行排序

尽可能保持 Markdown 文件的一级标题就是文件名(一级标题可以省略数字前缀)

右侧目录¶

右侧的目录是根据 Markdown 的 # 标题生成的, 目前设置的最大深度是 5 层

index.md¶

在每一个文件夹中都可以设置一个 index.md 文件, 这个文件的内容会作为点击该文件夹导航栏时时, 优先显示的内容

如果没有 index.md 文件的话, 点击该文件夹导航栏时, 则会跳转到该文件夹中字典序排序的第一个 Markdown 文件

注意: index.md 文件中, 请编写该文件夹内容的总结性内容, 请不要编写长篇正文

如果文件夹内只有一篇文章, 可以选择不创建 index.md 文件, 仅保留一篇正文 Markdown, 或者取消文件夹, 直接将 Markdown 文件直接放在上一层文件夹中

assets 文件夹¶

如果需要在正文中添加图片, 具体语法请参看 Markdown 语法文档

而 图片的源文件 请放置在与 引用其的 Markdown 文件 同一层目录的 assets 文件夹中, 而不是全部放置在 docs 目录的文件夹中

如果需要引用在线图片, 最好将其下载保存后引用, 以免链接失效, 导致图片缺失