3pp-mirror/docusaurus
1
0
Fork 0
mirror of https://github.com/facebook/docusaurus.git synced 2025-05-10 07:37:19 +02:00
Code Issues Projects Releases Packages Wiki Activity

docs: multiple documentation elaborations (#7519)

Browse source
This commit is contained in:
Joshua Chen 2022-05-28 21:24:01 +08:00 • committed by GitHub
parent ab566ecce3
commit f40dc31381
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 124 additions and 116 deletions
Download patch file Download diff file Expand all files Collapse all files

4
website/docs/advanced/ssg.md
View file

@ -8,12 +8,14 @@ description: Docusaurus statically renders your React code into HTML, allowing f
In [architecture](architecture.md), we mentioned that the theme is run in Webpack. But beware: that doesn't mean it always has access to browser globals! The theme is built twice: In [architecture](architecture.md), we mentioned that the theme is run in Webpack. But beware: that doesn't mean it always has access to browser globals! The theme is built twice:
- During **server-side rendering**, the theme is compiled in a sandbox called [React DOM Server](https://reactjs.org/docs/react-dom-server.html). You can see this as a "headless browser", where there is no `window` or `document`, only React. SSR produces static HTML pages. - During **server-side rendering**, the theme is compiled in a sandbox called [React DOM Server](https://reactjs.org/docs/react-dom-server.html). You can see this as a "headless browser", where there is no `window` or `document`, only React. SSR produces static HTML pages.
- During **client-side rendering**, the theme is compiled with standard React DOM, and has access to browser variables. CSR produces dynamic JavaScript. - During **client-side rendering**, the theme is compiled to JavaScript that gets eventually executed in the browser, so it has access to browser variables.
:::info SSR or SSG? :::info SSR or SSG?
_Server-side rendering_ and _static site generation_ can be different concepts, but we use them interchangeably. _Server-side rendering_ and _static site generation_ can be different concepts, but we use them interchangeably.
Strictly speaking, Docusaurus is a static site generator, because there's no server-side runtime—we statically render to HTML files that are deployed on a CDN, instead of dynamically pre-rendering on each request. This differs from the working model of [Next.js](https://nextjs.org/).
::: :::
Therefore, while you probably know not to access Node globals like `process` ([or can we?](#node-env)) or the `'fs'` module, you can't freely access browser globals either. Therefore, while you probably know not to access Node globals like `process` ([or can we?](#node-env)) or the `'fs'` module, you can't freely access browser globals either.

10
website/docs/api/docusaurus.config.js.md
View file

@ -425,7 +425,7 @@ module.exports = {
### `scripts` {#scripts} ### `scripts` {#scripts}
An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The `<script>` tags will be inserted in the HTML `<head>`. An array of scripts to load. The values can be either strings or plain objects of attribute-value maps. The `<script>` tags will be inserted in the HTML `<head>`. If you use a plain object, the only required attribute is `src`, and any other attributes are permitted (each one should have boolean/string values).
Note that `<script>` added here are render-blocking, so you might want to add `async: true`/`defer: true` to the objects. Note that `<script>` added here are render-blocking, so you might want to add `async: true`/`defer: true` to the objects.
@ -449,7 +449,7 @@ module.exports = {
### `stylesheets` {#stylesheets} ### `stylesheets` {#stylesheets}
An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The `<link>` tags will be inserted in the HTML `<head>`. An array of CSS sources to load. The values can be either strings or plain objects of attribute-value maps. The `<link>` tags will be inserted in the HTML `<head>`. If you use an object, the only required attribute is `href`, and any other attributes are permitted (each one should have boolean/string values).
- Type: `(string | Object)[]` - Type: `(string | Object)[]`
@ -468,6 +468,12 @@ module.exports = {
}; };
``` ```
:::info
By default, the `<link>` tags will have `rel="stylesheet"`, but you can explicitly add a custom `rel` value to inject any kind of `<link>` tag, not necessarily stylesheets.
:::
### `clientModules` {#clientModules} ### `clientModules` {#clientModules}
An array of [client modules](../advanced/client.md#client-modules) to load globally on your site. An array of [client modules](../advanced/client.md#client-modules) to load globally on your site.

2
website/docs/blog.mdx
View file

@ -70,7 +70,7 @@ This is my first post on Docusaurus 2.
A whole bunch of exploration to follow. A whole bunch of exploration to follow.
``` ```
The front matter is useful to add more metadata to your blog post, for example, author information, but Docusaurus will be able to infer all necessary metadata without the front matter. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-front-matter). The [front matter](./guides/markdown-features/markdown-features-intro.mdx#front-matter) is useful to add more metadata to your blog post, for example, author information, but Docusaurus will be able to infer all necessary metadata without the front matter. For all possible fields, see [the API documentation](api/plugins/plugin-content-blog.md#markdown-front-matter).
## Blog list {#blog-list} ## Blog list {#blog-list}

134
website/docs/guides/docs/docs-create-doc.mdx
View file

@ -18,25 +18,22 @@ website # root directory of your site
├── ... ├── ...
``` ```
At the top of the file, specify `id` and `title` in the front matter, so that Docusaurus will pick them up correctly when generating your site.
```md ```md
--- ---
id: greeting description: Create a doc page with rich content.
title: Hello
--- ---
## Hello from Docusaurus # Hello from Docusaurus
Are you ready to create the documentation site for your open source project? Are you ready to create the documentation site for your open source project?
### Headers ## Headers
will show up on the table of contents on the upper right 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. 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. ## 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. You can configure the TOC heading levels either per-document or in the theme configuration.
@ -48,47 +45,11 @@ The headers are well-spaced so that the hierarchy is clear.
- and you may nest them - and you may nest them
- multiple times - multiple times
### Custom id headers {#custom-id} ## Custom id headers {#custom-id}
With `{#custom-id}` syntax you can set your own header id. With `{#custom-id}` syntax you can set your own header id.
``` ```
This will render in the browser as follows:
```mdx-code-block
import BrowserWindow from '@site/src/components/BrowserWindow';
<BrowserWindow>
<h2>Hello from Docusaurus</h2>
Are you ready to create the documentation site for your open source project?
<h3>Headers</h3>
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.
<h3>Only h2 and h3 will be in the TOC by default.</h3>
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
<h3 id="custom-id">Custom id headers</h3>
With <code>{#custom-id}</code> syntax you can set your own header id.
</BrowserWindow>
```
:::note :::note
All files prefixed with an underscore (`_`) under the `docs` directory are treated as "partial" pages and will be ignored by default. All files prefixed with an underscore (`_`) under the `docs` directory are treated as "partial" pages and will be ignored by default.
@ -97,6 +58,10 @@ Read more about [importing partial pages](../markdown-features/markdown-features
::: :::
## 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](#dog-tags) feature introduced below requires using front matter. For all possible fields, see [the API documentation](../../api/plugins/plugin-content-docs.md#markdown-front-matter).
## Doc tags {#doc-tags} ## 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.md). Tags are passed in the front matter as a list of labels: Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the [docs sidebar](./sidebar/index.md). Tags are passed in the front matter as a list of labels:
@ -118,3 +83,84 @@ 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/). 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, `greeting.md` id is `greeting` and `guide/hello.md` id 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-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.md), 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.

74
website/docs/guides/docs/docs-introduction.md
View file

@ -14,76 +14,14 @@ Check the [Docs Plugin API Reference documentation](./../../api/plugins/plugin-c
::: :::
## Document ID {#document-id} Your site's documentation is organized by four levels, from lowest to highest:
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. 1. Individual pages.
2. Sidebars.
3. Versions.
4. Plugin instances.
For example, `greeting.md` id is `greeting` and `guide/hello.md` id is `guide/hello`. The guide will introduce them in that order: starting from [how individual pages can be configured](./docs-create-doc.mdx), to [how to create a sidebar or multiple ones](./sidebar/index.md), to [how to create and manage versions](./versioning.md), to [how to use multiple docs plugin instances](./docs-multi-instance.mdx).
```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
```
### Customizing doc URLs {#customizing-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-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`...
:::
## Home page docs {#home-page-docs}
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
```
## Docs-only mode {#docs-only-mode} ## Docs-only mode {#docs-only-mode}

16
website/docs/guides/markdown-features/markdown-features-intro.mdx
View file

@ -56,6 +56,22 @@ In general, you should only assume the _semantics_ of the markup (` ``` ` fences
</details> </details>
## Front matter {#front-matter}
Front matter is used to add metadata to your Markdown file. All content plugins have their own front matter schema, and use the front matter to enrich the default metadata inferred from the content or other configuration.
Front matter is provided at the very top of the file, enclosed by three dashes `---`. The content is parsed as [YAML](https://yaml.org/spec/1.2.2/).
```md
---
title: My Doc Title
more_data:
- Can be provided
- as: objects
or: arrays
---
```
## Quotes {#quotes} ## Quotes {#quotes}
Markdown quotes are beautifully styled: Markdown quotes are beautifully styled: