mirror of
https://github.com/facebook/docusaurus.git
synced 2025-05-10 15:47:23 +02:00
docs: archive v2 docs versions + create 2.x docs (#9472)
This commit is contained in:
Sébastien Lorber
GitHub
parent
495c7936b6
commit
10897416dc
462 changed files with 5 additions and 74654 deletions
|
|
@ -1,162 +0,0 @@
|
|||
---
|
||||
id: create-doc
|
||||
description: Create a Markdown Document
|
||||
slug: /create-doc
|
||||
---
|
||||
|
||||
# Create a doc
|
||||
|
||||
Create a Markdown file, `greeting.md`, and place it under the `docs` directory.
|
||||
|
||||
```bash
|
||||
website # root directory of your site
|
||||
├── docs
|
||||
│ └── greeting.md
|
||||
├── src
|
||||
│ └── pages
|
||||
├── docusaurus.config.js
|
||||
├── ...
|
||||
```
|
||||
|
||||
```md
|
||||
---
|
||||
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
|
||||
```
|
||||
|
||||
:::note
|
||||
|
||||
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](../markdown-features/markdown-features-react.mdx#importing-markdown).
|
||||
|
||||
:::
|
||||
|
||||
## Doc front matter {#doc-front-matter}
|
||||
|
||||
The [front matter](../markdown-features/markdown-features-intro.mdx#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](#doc-tags) feature introduced below requires using front matter. For all possible fields, see [the API documentation](../../api/plugins/plugin-content-docs.mdx#markdown-front-matter).
|
||||
|
||||
## Doc tags {#doc-tags}
|
||||
|
||||
Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar/index.mdx). Tags are passed in the front matter as a list of labels:
|
||||
|
||||
```md "your-doc-page.md"
|
||||
---
|
||||
id: doc-with-tags
|
||||
title: A doc with tags
|
||||
tags:
|
||||
- Demo
|
||||
- Getting started
|
||||
---
|
||||
```
|
||||
|
||||
:::tip
|
||||
|
||||
Tags can also be declared with `tags: [Demo, Getting started]`.
|
||||
|
||||
Read more about all the possible [Yaml array syntaxes](https://www.w3schools.io/file/yaml-arrays/).
|
||||
|
||||
:::
|
||||
|
||||
## Organizing folder structure {#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 {#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`.
|
||||
|
||||
```bash
|
||||
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`.
|
||||
|
||||
```md
|
||||
---
|
||||
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 {#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:
|
||||
|
||||
```bash
|
||||
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`:
|
||||
|
||||
```md
|
||||
---
|
||||
slug: /bonjour
|
||||
---
|
||||
|
||||
Lorem ipsum
|
||||
```
|
||||
|
||||
`slug` will be appended to the doc plugin's `routeBasePath`, which is `/docs` by default. See [Docs-only mode](docs-introduction.mdx#docs-only-mode) for how to remove the `/docs` part from the URL.
|
||||
|
||||
:::note
|
||||
|
||||
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:
|
||||
|
||||
```md
|
||||
---
|
||||
id: my-home-doc
|
||||
slug: /
|
||||
---
|
||||
|
||||
Lorem ipsum
|
||||
```
|
||||
|
||||
### Sidebars {#sidebars}
|
||||
|
||||
When using [autogenerated sidebars](./sidebar/autogenerated.mdx), 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue