mirror of
https://github.com/ZSCNetSupportDept/website.git
synced 2026-02-10 12:18:59 +08:00
88 lines
4.8 KiB
Markdown
88 lines
4.8 KiB
Markdown
---
|
||
|
||
description: 如何组织文档的结构
|
||
|
||
---
|
||
|
||
# 文件的组织
|
||
所有的文档都采用Markdown编写，如果你对它不熟悉的话，建议看"撰写内容"板块，这里不再赘述。这里讲一讲Docusaurus特定的，组织文档的技巧。
|
||
|
||
## Sidebar
|
||
|
||
如果你使用电脑端访问本站的话，你可以看到在站点的左边有你当前访问的文档(wiki或者开发组文档)的目录，我们称之为Sidebar。
|
||
|
||
Sidebar本来是高度可配置的，但是我们的Sidebar配置很简单：自动搜索，原样反映`/docs/wiki`和`/docs/devdocs`下的所有文件和子目录中的文件。也就是说，这两个目录下的每个`.md`文件，都对应sidebar中的一篇文章；每个文件夹，都对应着Sidebar中的一个子栏目（右边有箭头可以展开的那个，官方的行话叫做Category,"类别"）。
|
||
|
||
这非常直观，所以如果你会Markdown的话，应该很快就可以上手开始编写文章，不过在编写之前，你需要知道如下事情：
|
||
|
||
## index.md
|
||
系统会特殊处理每个文件夹下，名为`index.md`的文件。它会被当作这个子栏目的概述文件。当你点击Sidebar的子栏目（而不是右边的箭头）时，网站就会显现相应文件夹下的`index.md`文件。
|
||
|
||
> *官方文档:[链接](https://docusaurus.io/zh-CN/docs/sidebar/autogenerated#category-index-convention)，实际上使用`README.md`也可，不过本项目约定使用`index.md`*
|
||
|
||
## 给文件编号以排序
|
||
默认情况下，系统会在Sidebar中按照拼音或首字母的顺序从上到下排列文档。但是如果我们想让某些文档排在前面，某些在后面，按一定的顺序排列文档该怎么办？
|
||
|
||
我们的做法是，将每个`.md`文件前面加上一个数字前缀：
|
||
|
||
例如，如果你在目录`wiki编写教程`下有如下文件：`如何快速编写wiki.md`，`编写wiki的高级技巧.md`，`额外说明.md`；如果直接这样放上去的话，系统会如下排列这些文章：
|
||
|
||
|
||
|
||
这完全不是我们想要的！我们想要以主题由浅入深的顺序排列文章..那么应该怎么办？正确的做法是把文件重命名为如下格式：`01-如何快速编写wiki.md`，`02-编写wiki的高级技巧.md`，`03-额外说明.md`，此时，系统会如下显示：
|
||
|
||
|
||
|
||
系统在构建时会自动去除数字前标，另外这个操作对于子文件夹也适用的。
|
||
|
||
> *官方文档:[链接](https://docusaurus.io/zh-CN/docs/sidebar/autogenerated#using-number-prefixes)，官方实际上推荐在每个文档内部使用元数据的方式来标记位置，不过我们还是使用这种修改文件名的方式。因为这样简单方便，直观而且能集中管理。* <br></br> 当然我们的方法在调整顺序时可能需要连锁修改很多文件名，不过方案总归要权衡利弊～
|
||
|
||
## 使用"_"忽略某些文件
|
||
系统会忽略以`_`开头的所有文件和文件夹，它们并不会参与到构建中，所以如果你在写一些东西，而且暂时不想把它们放出来的话，可以先用`_`注释掉它们。
|
||
|
||
> *官方文档:[链接](https://docusaurus.io/zh-CN/docs/creating-pages#routing)*
|
||
|
||
## docs-card
|
||
在站内你可以看到这样的组件：
|
||
|
||
它们通常出现在`index.md`中，以一系列卡片的形式展现了该子文件夹中的文件和文件夹。
|
||
|
||
要使用它们，请在markdown中添加如下代码：
|
||
|
||
```
|
||
|
||
import DocCardList from '@theme/DocCardList';
|
||
|
||
<DocCardList className="docs-card" />
|
||
|
||
```
|
||
> *官方文档:[链接](https://docusaurus.io/zh-CN/docs/sidebar/items#embedding-generated-index-in-doc-page) <br></br> 注意，class是必要的，因为我们修改了`h2`的默认样式，而docs-card默认把标题渲染成`h2`，我们专门写了一段CSS把样式在docs-card里面改了回来。*
|
||
### 为文件添加简述
|
||
在每个文件的下面有一行小字，这是这个文件的简述。默认情况下，系统会把`h1`下的第一句话当作简述，如果你想自定义简述的话，请在那篇文章的开头添加以下内容：
|
||
|
||
```
|
||
|
||
---
|
||
|
||
description: 在这里填入你的简述
|
||
|
||
---
|
||
|
||
```
|
||
|
||
> *官方文档:[链接1](https://docusaurus.io/zh-CN/docs/sidebar/autogenerated#doc-item-metadata)，[链接2](https://docusaurus.io/zh-CN/docs/markdown-features/head-metadata#markdown-page-description)*
|
||
|
||
### 为目录设置简述
|
||
当docs-card所展示的含有子目录时，可以通过在该子目录下设置一个名为`_category_.json`的文件来添加简述：
|
||
|
||
```
|
||
|
||
{
|
||
"description": "在这里填入你的简述"
|
||
}
|
||
|
||
|
||
```
|
||
|
||
> *官方文档:[链接](https://docusaurus.io/zh-CN/docs/sidebar/autogenerated#category-item-metadata) <br></br>官方文档好像说yaml也可以，我没怎么用过，你们可以尝试下*
|