docs(v2): Reorganize/split the guides doc sections (#3975)

* docs reorg * refactor docs/markdown features section * fix broken links after docs refactor
facebook · Dec 30, 2020 · d99d53a · d99d53a
1 parent a0c5177
commit d99d53a
Show file tree

Hide file tree

Showing 20 changed files with 1,347 additions and 1,192 deletions.
diff --git a/website/docs/api/plugins/plugin-content-docs.md b/website/docs/api/plugins/plugin-content-docs.md
@@ -4,7 +4,7 @@ title: '📦 plugin-content-docs'
 slug: '/api/plugins/@docusaurus/plugin-content-docs'
 ---
 
-Provides the [Docs](markdown-features.mdx) functionality and is the default docs plugin for Docusaurus.
+Provides the [Docs](../../guides/docs/docs-introduction.md) functionality and is the default docs plugin for Docusaurus.
 
 ## Installation
 
@@ -133,3 +133,36 @@ module.exports = {
   ],
 };
 ```
+
+## Markdown Frontmatter
+
+Markdown documents can use the following markdown frontmmatter metadata fields, enclosed by a line `---` on either side:
+
+- `id`: A unique document id. If this field is not present, the document's `id` will default to its file name (without the extension).
+- `title`: The title of your document. If this field is not present, the document's `title` will default to its `id`.
+- `hide_title`: Whether to hide the title at the top of the doc. By default it is `false`.
+- `hide_table_of_contents`: Whether to hide the table of contents to the right. By default it is `false`.
+- `sidebar_label`: The text shown in the document sidebar and in the next/previous button for this document. If this field is not present, the document's `sidebar_label` will default to its `title`.
+- `custom_edit_url`: The URL for editing this document. If this field is not present, the document's edit URL will fall back to `editUrl` from options fields passed to `docusaurus-plugin-content-docs`.
+- `keywords`: Keywords meta tag for the document page, for search engines.
+- `description`: The description of your document, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines. If this field is not present, it will default to the first line of the contents.
+- `image`: Cover or thumbnail image that will be used when displaying the link to your post.
+
+Example:
+
+```yml
+---
+id: doc-markdown
+title: Markdown Features
+hide_title: false
+hide_table_of_contents: false
+sidebar_label: Markdown :)
+custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md
+description: How do I find you when I cannot solve this problem
+keywords:
+  - docs
+  - docusaurus
+image: https://i.imgur.com/mErPwqL.png
+---
+My Document Markdown content
+```
diff --git a/website/docs/api/themes/theme-configuration.md b/website/docs/api/themes/theme-configuration.md
@@ -399,7 +399,7 @@ module.exports = {
 
 :::note
 
-If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the [docs for guidance](markdown-features.mdx#line-highlighting).
+If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the [docs for guidance](../../guides/markdown-features/markdown-features-code-blocks.mdx#line-highlighting).
 
 :::
 

diff --git a/website/docs/api/themes/theme-live-codeblock.md b/website/docs/api/themes/theme-live-codeblock.md
@@ -4,7 +4,7 @@ title: '📦 theme-live-codeblock'
 slug: '/api/themes/@docusaurus/theme-live-codeblock'
 ---
 
-This theme provides a `@theme/CodeBlock` component that is powered by react-live. You can read more on [interactive code editor](markdown-features.mdx#interactive-code-editor) documentation.
+This theme provides a `@theme/CodeBlock` component that is powered by react-live. You can read more on [interactive code editor](../../guides/markdown-features/markdown-features-code-blocks.mdx#interactive-code-editor) documentation.
 
 ```bash npm2yarn
 npm install --save @docusaurus/theme-live-codeblock

diff --git a/website/docs/guides/docs/docs-create-doc.mdx b/website/docs/guides/docs/docs-create-doc.mdx
@@ -0,0 +1,75 @@
+---
+id: create-doc
+title: Create a doc
+description: Create a Markdown Document
+slug: /create-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
+├── ...
+```
+
+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.
+
+```yml
+---
+id: greeting
+title: Hello
+---
+
+## 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
+
+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
+```
+
+This will render in the browser as follows:
+
+import BrowserWindow from '@site/src/components/BrowserWindow';
+
+<BrowserWindow url="http://localhost:3000">
+
+<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</h3>
+
+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
+
+</BrowserWindow>
diff --git a/website/docs/docs.md → ...ite/docs/guides/docs/docs-introduction.md b/website/docs/docs.md → ...ite/docs/guides/docs/docs-introduction.md
@@ -1,7 +1,8 @@
 ---
-id: docs-introduction
+id: introduction
 title: Docs Introduction
 sidebar_label: Introduction
+slug: /docs-introduction
 ---
 
 The docs feature provides users with a way to organize Markdown files in a hierarchical format.
@@ -74,6 +75,6 @@ You should delete the existing homepage at `./src/pages/index.js`, or else there
 
 :::tip
 
-There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](blog.md#blog-only-mode).
+There's also a "blog-only mode" for those who only want to use the blog feature of Docusaurus 2. You can use the same method detailed above. Follow the setup instructions on [Blog-only mode](../../blog.md#blog-only-mode).
 
 :::
diff --git a/website/docs/guides/docs/docs-markdown-features.mdx b/website/docs/guides/docs/docs-markdown-features.mdx
@@ -0,0 +1,28 @@
+---
+id: markdown-features
+title: Docs Markdown Features
+description: Docusaurus Markdown features that are specific to the docs plugin
+slug: /docs-markdown-features
+---
+
+Docs can use any [Markdown feature](../markdown-features/markdown-features-intro.mdx), and have a few additional Docs-specific markdown features.
+
+## Markdown frontmatter
+
+Markdown docs have their own [Markdown frontmatter](../../api/plugins/plugin-content-docs.md#markdown-frontmatter)
+
+## Referencing other documents
+
+If you want to reference another document file, you could use the name of the document you want to reference. Docusaurus will convert the file path to be the final website path (and remove the `.md`).
+
+For example, if you are in `doc2.md` and you want to reference `doc1.md` and `folder/doc3.md`:
+
+```md
+I am referencing a [document](doc1.md). Reference to another [document in a folder](folder/doc3.md).
+
+[Relative document](../doc2.md) referencing works as well.
+```
+
+One benefit of this approach is that the links to external files will still work if you are viewing the file on GitHub.
+
+Another benefit, for versioned docs, is that one versioned doc will link to another doc of the exact same version.
diff --git a/website/docs/sidebar.md → website/docs/guides/docs/sidebar.md b/website/docs/sidebar.md → website/docs/guides/docs/sidebar.md
@@ -1,5 +1,5 @@
 ---
-id: docs-sidebar
+id: sidebar
 title: Sidebar
 slug: /sidebar
 ---
@@ -105,7 +105,7 @@ By default, the doc page the user is reading will display the sidebar that it is
 
 For example, with the above example, when displaying the `doc2` page, the sidebar will contain the items of `secondSidebar` only. Another example of multiple sidebars is the `API` and `Docs` sections on the Docusaurus website.
 
-For more information about sidebars and how they relate to doc pages, see [Navbar doc link](./api/themes/theme-configuration.md#navbar-doc-link).
+For more information about sidebars and how they relate to doc pages, see [Navbar doc link](../../api/themes/theme-configuration.md#navbar-doc-link).
 
 ## Understanding sidebar items
 

diff --git a/website/docs/versioning.md → website/docs/guides/docs/versioning.md b/website/docs/versioning.md → website/docs/guides/docs/versioning.md
@@ -1,6 +1,7 @@
 ---
 id: versioning
 title: Versioning
+slug: /versioning
 ---
 
 You can use the version script to create a new documentation version based on the latest content in the `docs` directory. That specific set of documentation will then be preserved and accessible even as the documentation in the `docs` directory changes moving forward.
@@ -61,7 +62,7 @@ npm run docusaurus docs:version 1.1.0
 When tagging a new version, the document versioning mechanism will:
 
 - Copy the full `docs/` folder contents into a new `versioned_docs/version-<version>/` folder.
-- Create a versioned sidebars file based from your current [sidebar](docs.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-<version>-sidebars.json`.
+- Create a versioned sidebars file based from your current [sidebar](docs-introduction.md#sidebar) configuration (if it exists) - saved as `versioned_sidebars/version-<version>-sidebars.json`.
 - Append the new version number to `versions.json`.
 
 ## Docs
@@ -165,7 +166,7 @@ Docusaurus defaults work great for the first usecase.
 
 The docs in `./docs` will be served at `/docs/1.0.0` instead of `/docs/next`, and `1.0.0` will become the default version we link to in the navbar dropdown, and you will only need to maintain a single `./docs` folder.
 
-See [docs plugin configuration](./api/plugins/plugin-content-docs.md) for more details.
+See [docs plugin configuration](../../api/plugins/plugin-content-docs.md) for more details.
 
 ### Version your documentation only when needed
 

diff --git a/website/docs/guides/markdown-features/markdown-features-admonitions.mdx b/website/docs/guides/markdown-features/markdown-features-admonitions.mdx
@@ -0,0 +1,86 @@
+---
+id: admonitions
+title: Admonitions
+description: Handling admonitions/callouts in Docusaurus Markdown
+slug: /markdown-features/admonitions
+---
+
+In addition to the basic Markdown syntax, we use [remark-admonitions](https://github.com/elviswolcott/remark-admonitions) alongside MDX to add support for admonitions. Admonitions are wrapped by a set of 3 colons.
+
+Example:
+
+    :::note
+
+    The content and title *can* include markdown.
+
+    :::
+
+    :::tip You can specify an optional title
+
+    Heads up! Here's a pro-tip.
+
+    :::
+
+    :::info
+
+    Useful information.
+
+    :::
+
+    :::caution
+
+    Warning! You better pay attention!
+
+    :::
+
+    :::danger
+
+    Danger danger, mayday!
+
+    :::
+
+:::note
+
+The content and title _can_ include markdown.
+
+:::
+
+:::tip You can specify an optional title
+
+Heads up! Here's a pro-tip.
+
+:::
+
+:::info
+
+Useful information.
+
+:::
+
+:::caution
+
+Warning! You better pay attention!
+
+:::
+
+:::danger
+
+Danger danger, mayday!
+
+:::
+
+## Specifying title
+
+You may also specify an optional title
+
+    :::note Your Title
+
+    The content and title *can* include markdown.
+
+    :::
+
+:::note Your Title
+
+The content and title _can_ include Markdown.
+
+:::
-Original file line number
+Diff line change
@@ Expand Up / @@ -399,7 +399,7 @@ module.exports = { @@
     :::note
-    If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the [docs for guidance](markdown-features.mdx#line-highlighting).
+    If you use the line highlighting Markdown syntax, you might need to specify a different highlight background color for the dark mode syntax highlighting theme. Refer to the [docs for guidance](../../guides/markdown-features/markdown-features-code-blocks.mdx#line-highlighting).
     :::
@@ Expand Down @@