创建文档
创建一份 Markdown 文档，文件名为 greeting.md，并将该文档放置于 docs 目录下。
website # 网站根目录
├── docs
│ └── greeting.md
├── src
│ └── pages
├── docusaurus.config.js
├── ...
---
description: Create a doc page with rich content.
---
# Hello from Docusaurus
您准备好为您的开源项目创建文档站点了吗？
## Headers
标题将显示在右上方的目录中
以便用户无需向下滚动，甚至无需阅读更多内容，便可了解此页的梗概。
## 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.
良好的标题间距，让文章结构更清晰。
- lists will help you
- present the key points
- that you want your users to remember
- and you may nest them
- multiple times
## Custom ID headers {#custom-id}
With `{#custom-id}` syntax you can set your own header ID.
All files prefixed with an underscore (_) under the docs directory are treated as "partial" pages and will be ignored by default.
Read more about importing partial pages.
Doc front matter
The front matter is used to provide additional metadata for your doc page. Front matter is optional—Docusaurus will be able to infer all necessary metadata without the front matter. For example, the doc tags feature introduced below requires using front matter. For all possible fields, see the API documentation.
Doc tags
Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the docs sidebar. Tags are passed in the front matter as a list of labels:
---
id: doc-with-tags
title: A doc with tags
tags:
- Demo
- Getting started
---
Tags can also be declared with tags: [Demo, Getting started].
Read more about all the possible Yaml array syntaxes.
Organizing folder structure
How the Markdown files are arranged under the docs folder can have multiple impacts on Docusaurus content generation. However, most of them can be decoupled from the file structure.
Document ID
Every document has a unique id. By default, a document id is the name of the document (without the extension) relative to the root docs directory.
For example, the ID of greeting.md is greeting, and the ID of guide/hello.md is guide/hello.
website # Root directory of your site
└── docs
├── greeting.md
└── guide
└── hello.md
However, the last part of the id can be defined by the user in the front matter. For example, if guide/hello.md's content is defined as below, its final id is guide/part1.
---
id: part1
---
Lorem ipsum
The ID is used to refer to a document when hand-writing sidebars, or when using docs-related layout components or hooks.
Doc URLs
By default, a document's URL location is its file path relative to the docs folder. Use the slug front matter to change a document's URL.
For example, suppose your site structure looks like this:
website # Root directory of your site
└── docs
└── guide
└── hello.md
By default hello.md will be available at /docs/guide/hello. You can change its URL location to /docs/bonjour:
---
slug: /bonjour
---
Lorem ipsum
slug will be appended to the doc plugin's routeBasePath, which is /docs by default. See Docs-only mode for how to remove the /docs part from the URL.
It is possible to use:
- absolute slugs:
slug: /mySlug,slug: /... - relative slugs:
slug: mySlug,slug: ./../mySlug...
If you want a document to be available at the root, and have a path like https://docusaurus.io/docs/, you can use the slug front matter:
---
id: my-home-doc
slug: /
---
Lorem ipsum
Sidebars
When using autogenerated sidebars, the file structure will determine the sidebar structure.
Our recommendation for file system organization is: make your file system mirror the sidebar structure (so you don't need to handwrite your sidebars.js file), and use the slug front matter to customize URLs of each document.