Skip to content

Commit

Permalink
docs: multiple documentation elaborations (#7519)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Josh-Cena
Josh-Cena authored May 28, 2022
1 parent ab566ec commit f40dc31
Show file tree
Hide file tree
Showing 6 changed files with 123 additions and 115 deletions.
4 changes: 3 additions & 1 deletion website/docs/advanced/ssg.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:

- 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?

_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.
Expand Down
10 changes: 8 additions & 2 deletions website/docs/api/docusaurus.config.js.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -425,7 +425,7 @@ module.exports = {

### `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.

Expand All @@ -449,7 +449,7 @@ module.exports = {

### `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)[]`

Expand All @@ -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}

An array of [client modules](../advanced/client.md#client-modules) to load globally on your site.
Expand Down
2 changes: 1 addition & 1 deletion website/docs/blog.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,7 @@ This is my first post on Docusaurus 2.
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}

Expand Down
132 changes: 89 additions & 43 deletions website/docs/guides/docs/docs-create-doc.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
---
id: greeting
title: Hello
description: Create a doc page with rich content.
---

## Hello from Docusaurus
# Hello from Docusaurus

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

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.

Expand All @@ -48,73 +45,122 @@ The headers are well-spaced so that the hierarchy is clear.
- and you may nest them
- multiple times

### Custom id headers {#custom-id}
## Custom id headers {#custom-id}

With `{#custom-id}` syntax you can set your own header id.
```

This will render in the browser as follows:
:::note

```mdx-code-block
import BrowserWindow from '@site/src/components/BrowserWindow';
All files prefixed with an underscore (`_`) under the `docs` directory are treated as "partial" pages and will be ignored by default.

<BrowserWindow>
Read more about [importing partial pages](../markdown-features/markdown-features-react.mdx#importing-markdown).

<h2>Hello from Docusaurus</h2>
:::

Are you ready to create the documentation site for your open source project?
## Doc front matter {#doc-front-matter}

<h3>Headers</h3>
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).

will show up on the table of contents on the upper right
## Doc tags {#doc-tags}

So that your users will know what this page is all about without scrolling down or even without reading too much.
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:

```md "your-doc-page.md"
---
id: doc-with-tags
title: A doc with tags
tags:
- Demo
- Getting started
---
```

<h3>Only h2 and h3 will be in the TOC by default.</h3>
:::tip

You can configure the TOC heading levels either per document or in the theme configuration.
Tags can also be declared with `tags: [Demo, Getting started]`.

The headers are well-spaced so that the hierarchy is clear.
Read more about all the possible [Yaml array syntaxes](https://www.w3schools.io/file/yaml-arrays/).

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

## 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.

<h3 id="custom-id">Custom id headers</h3>
### Document ID {#document-id}

With <code>{#custom-id}</code> syntax you can set your own header 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.

</BrowserWindow>
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
```

:::note
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`.

All files prefixed with an underscore (`_`) under the `docs` directory are treated as "partial" pages and will be ignored by default.
```md
---
id: part1
---

Read more about [importing partial pages](../markdown-features/markdown-features-react.mdx#importing-markdown).
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 tags {#doc-tags}
### Doc URLs {#doc-urls}

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:
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.

```md "your-doc-page.md"
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
---
id: doc-with-tags
title: A doc with tags
tags:
- Demo
- Getting started
slug: /bonjour
---

Lorem ipsum
```

:::tip
`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.

Tags can also be declared with `tags: [Demo, Getting started]`.
:::note

Read more about all the possible [Yaml array syntaxes](https://www.w3schools.io/file/yaml-arrays/).
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 changes: 6 additions & 68 deletions website/docs/guides/docs/docs-introduction.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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`.

```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
```
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).

## Docs-only mode {#docs-only-mode}

Expand Down
16 changes: 16 additions & 0 deletions website/docs/guides/markdown-features/markdown-features-intro.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,22 @@ In general, you should only assume the _semantics_ of the markup (` ``` ` fences

</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}

Markdown quotes are beautifully styled:
Expand Down

0 comments on commit f40dc31

Please sign in to comment.