diff --git a/docs/devdocs/03-开发组网站/02-文件的组织.md b/docs/devdocs/03-开发组网站/02-文件的组织.md new file mode 100644 index 0000000..ba9614f --- /dev/null +++ b/docs/devdocs/03-开发组网站/02-文件的组织.md @@ -0,0 +1,87 @@ +--- + +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`;如果直接这样放上去的话,系统会如下排列这些文章: + +![演示Sidebar](/img/devdocs/build-docs.png) + +这完全不是我们想要的!我们想要以主题由浅入深的顺序排列文章..那么应该怎么办?正确的做法是把文件重命名为如下格式:`01-如何快速编写wiki.md`,`02-编写wiki的高级技巧.md`,`03-额外说明.md`,此时,系统会如下显示: + +![演示Sidebar-1](/img/devdocs/build-docs-2.png) + +系统在构建时会自动去除数字前标,另外这个操作对于子文件夹也适用的。 + +> *官方文档:[链接](https://docusaurus.io/zh-CN/docs/sidebar/autogenerated#using-number-prefixes),官方实际上推荐在每个文档内部使用元数据的方式来标记位置,不过我们还是使用这种修改文件名的方式。因为这样简单方便,直观而且能集中管理。*

当然我们的方法在调整顺序时可能需要连锁修改很多文件名,不过方案总归要权衡利弊~ + +## 使用"_"忽略某些文件 +系统会忽略以`_`开头的所有文件和文件夹,它们并不会参与到构建中,所以如果你在写一些东西,而且暂时不想把它们放出来的话,可以先用`_`注释掉它们。 + +> *官方文档:[链接](https://docusaurus.io/zh-CN/docs/creating-pages#routing)* + +## docs-card +在站内你可以看到这样的组件: +![cards](/img/devdocs/docs-card.png) +它们通常出现在`index.md`中,以一系列卡片的形式展现了该子文件夹中的文件和文件夹。 + +要使用它们,请在markdown中添加如下代码: + +``` + +import DocCardList from '@theme/DocCardList'; + + + +``` +> *官方文档:[链接](https://docusaurus.io/zh-CN/docs/sidebar/items#embedding-generated-index-in-doc-page)

注意,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)

官方文档好像说yaml也可以,我没怎么用过,你们可以尝试下* diff --git a/static/img/devdocs/build-docs-2.png b/static/img/devdocs/build-docs-2.png new file mode 100644 index 0000000..8065c72 Binary files /dev/null and b/static/img/devdocs/build-docs-2.png differ diff --git a/static/img/devdocs/build-docs.png b/static/img/devdocs/build-docs.png new file mode 100644 index 0000000..aa3a9d2 Binary files /dev/null and b/static/img/devdocs/build-docs.png differ diff --git a/static/img/devdocs/docs-card.png b/static/img/devdocs/docs-card.png new file mode 100644 index 0000000..aa8487c Binary files /dev/null and b/static/img/devdocs/docs-card.png differ