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