chore: release Docusaurus v3.4 (#10186)

website/versioned_docs/version-3.4.0/guides/docs/docs-create-doc.mdx

@@ -0,0 +1,192 @@
+---
+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}
+
+Tags are declared in the front matter and introduce another dimension of categorization in addition to the [docs sidebar](./sidebar/index.mdx).
+
+It is possible to define tags inline, or to reference predefined tags declared in a [`tags file`](../../api/plugins/plugin-content-docs.mdx#tags-file) (optional, usually `docs/tags.yml`).
+
+In the following example:
+
+- `docusaurus` references a predefined tag key declared in `docs/tags.yml`
+- `Releases` is an inline tag, because it does not exist in `docs/tags.yml`
+
+```md title="docs/my-doc.md"
+---
+tags:
+  - Releases
+  - docusaurus
+---
+
+# Title
+
+Content
+```
+
+```yml title="docs/tags.yml"
+docusaurus:
+  label: 'Docusaurus'
+  permalink: '/docusaurus'
+  description: 'Docs related to the Docusaurus framework'
+```
+
+:::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, with a few exceptions. Namely, if a file is named one the following, the file name won't be included in the URL:
+
+- Named as `index` (case-insensitive): `docs/Guides/index.md`
+- Named as `README` (case-insensitive): `docs/Guides/README.mdx`
+- Same name as parent folder: `docs/Guides/Guides.md`
+
+In all cases, the default slug would only be `/Guides`, without the `/index`, `/README`, or duplicate `/Guides` segment.
+
+:::note
+
+This convention is exactly the same as [the category index convention](./sidebar/autogenerated.mdx#category-index-convention). However, the `isCategoryIndex` configuration does _not_ affect the document URL.
+
+:::
+
+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.