创建文档

创建一个 Markdown 文件，greeting.md，并将其放在docs目录下。

website # root directory of your site
├── docs
│   └── greeting.md
├── src
│   └── pages
├── docusaurus.config.js
├── ...

---
description: Create a doc page with rich content.
---

# Hello from Docusaurus

Are you ready to create the documentation site for your open source project?

## Headers

will show up on the table of contents on the upper right

So that your users will know what this page is all about without scrolling down or even without reading too much.

## Only h2 and h3 will be in the TOC by default.

You can configure the TOC heading levels either per-document or in the theme configuration.

The headers are well-spaced so that the hierarchy is clear.

- lists will help you
- present the key points
- that you want your users to remember
  - and you may nest them
    - multiple times

备注

在docs目录下，所有以下划线(_)为前缀的文件都被视为partial页面，默认情况下将被忽略。

阅读更多关于导入部分页面的信息.

文档页前

页前用于为文档页面提供额外的元数据。页前是 optional—Docusaurus 将能够在没有前面内容的情况下推断所有必要的元数据。例如，下面介绍的文档标签特性需要使用前置内容。对于所有可能的字段，请参阅API 文档。

文档标签

您还可以选择向文档页面添加标记，这将引入除了文档侧边栏之外的另一个分类维度。标签以标签列表的形式在前台传递:

---
id: doc-with-tags
title: A doc with tags
tags:
  - Demo
  - Getting started
---

提示

标签也可以用Tags: [Demo, Getting started]来声明。

阅读更多关于所有可能的Yaml 数组语法.

组织文件夹结构

Markdown 文件在docs文件夹下的排列方式会对 Docusaurus 内容的生成产生多重影响。然而，它们中的大多数可以与文件结构解耦。

文档 ID

每个文档都有一个唯一的id。默认情况下，文档id是相对于根文档目录的文档名称(不带扩展名)。

例如，greing.md的 ID 为greeting，guide/hello.md的 ID 为guide/hello。

website # Root directory of your site
└── docs
   ├── greeting.md
   └── guide
      └── hello.md

然而，id的最后一部分可以由用户在前面定义。例如，如果guide/hello.md的内容定义如下，它的最终id是guide/part1。

---
id: part1
---

Lorem ipsum

当手写侧边栏或使用与文档相关的布局组件或钩子时，ID 用于引用文档。

文档

默认情况下，文档的 URL 位置是相对于docs文件夹的文件路径。使用slug前面的内容来更改文档的 URL。

例如，假设你的网站结构是这样的:

website # Root directory of your site
└── docs
    └── guide
        └── hello.md

默认情况下，hello.md将在/docs/guide/hello处可用。你可以把它的 URL 地址改为/docs/bonjour:

---
slug: /bonjour
---

Lorem ipsum

slug将被添加到 doc 插件的routeBasePath中，默认为/docs。请参阅docs-only 模式了解如何从 URL 中删除/docs部分。

备注

可以使用:

• 绝对 slugs: slug: /mySlug, slug: /...
• 相对 slugs: slug: mySlug, slug: ./../mySlug...

如果你想让一个文档在根目录下可用，并且有一个像https://docusaurus.io/docs/这样的路径，你可以使用 slug front matter:

---
id: my-home-doc
slug: /
---

Lorem ipsum

侧边栏

当使用自动生成边栏时，文件结构将决定侧边栏的结构。

我们对文件系统组织的建议是:让你的文件系统镜像侧边栏结构(这样你就不需要手写你的sidebars.js文件)，并使用slug前面的内容来定制每个文档的 url。