feat(v2): auto-generated sidebars, frontmatter-less sites (#4582)

* POC of autogenerated sidebars

* use combine-promises utility lib

* autogenerated sidebar poc working

* Revert "autogenerated sidebar poc working"

This reverts commit c81da980

* POC of auto-generated sidebars for community docs

* update tests

* add initial test suite for autogenerated sidebars + fix some edge cases

* Improve autogen sidebars: strip more number prefixes in folder breadcrumb + slugs

* fix typo!

* Add tests for partially generated sidebars + fix edge cases + extract sidebar generation code

* Ability to read category metadatas file from a file in the category

* fix tests

* change position of API

* ability to extract number prefix

* stable system to enable position frontmatter

* fix tests for autogen sidebar position

* renamings

* restore community sidebars

* rename frontmatter position -> sidebar_position

* make sidebarItemsGenerator fn configurable

* minor changes

* rename dirPath => dirName

* Make the init template use autogenerated sidebars

* fix options

* fix docusaurus site: remove test docs

* add _category_ file to docs pathsToWatch

* add _category_ file to docs pathsToWatch

* tutorial: use sidebar_position instead of file number prefixes

* Adapt Docusaurus tutorial for autogenerated sidebars

* remove slug: /

* polish the homepage template

* rename _category_ sidebar_position to just "position"

* test for custom sidebarItemsGenerator fn

* fix category metadata + add link to report tutorial issues

* fix absolute path breaking tests

* fix absolute path breaking tests

* Add test for floating number sidebar_position

* add sidebarItemsGenerator unit tests

* add processSidebars unit tests

* Fix init template broken links

* windows test

* increase code translations test timeout

* cleanup mockCategoryMetadataFiles after windows test fixed

* update init template positions

* fix windows tests

* fix comment

* Add autogenerated sidebar items documentation + rewrite the full sidebars page doc

* add useful comment

* fix code block title

packages/docusaurus-init/templates/classic/docs/create-a-document.md

@@ -1,38 +0,0 @@
----
-title: Create a Document
----
-
-Documents are a **group of pages** connected through a **sidebar**, a **previous/next navigation** and **versioning**.
-
-## Create a Document
-
-Create a markdown file at `docs/my-doc.md`:
-
-```mdx title="docs/hello.md"
----
-title: Hello, World!
----
-
-## Hello, World!
-
-This is your first document in **Docusaurus**, Congratulations!
-```
-
-A new document is now available at `http://localhost:3000/docs/hello`.
-
-## Add your document to the sidebar
-
-Add `hello` to the `sidebars.js` file:
-
-```diff title="sidebars.js"
-module.exports = {
-  docs: [
-    {
-      type: 'category',
-      label: 'Docusaurus Tutorial',
--     items: ['getting-started', 'create-a-doc', ...],
-+     items: ['getting-started', 'create-a-doc', 'hello', ...],
-    },
-  ],
-};
-```

packages/docusaurus-init/templates/classic/docs/intro.md

@@ -1,11 +1,16 @@
 ---
-title: Getting Started
-slug: /
+sidebar_position: 1
 ---
 
-Get started by **creating a new site**
+# Tutorial Intro
 
-Or **try Docusaurus immediately** with **[new.docusaurus.io](https://new.docusaurus.io)** (CodeSandbox).
+Let's discover **Docusaurus in less than 5 minutes**.
+
+## Getting Started
+
+Get started by **creating a new site**.
+
+Or **try Docusaurus immediately** with **[new.docusaurus.io](https://new.docusaurus.io)**.
 
 ## Generate a new site
 

packages/docusaurus-init/templates/classic/docs/tutorial-basics/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Tutorial - Basics",
+  "position": 2
+}

packages/docusaurus-init/templates/classic/docs/tutorial-basics/congratulations.md

@@ -1,14 +1,16 @@
 ---
-title: Congratulations!
+sidebar_position: 6
 ---
 
-Congratulations on making it this far!
+# Congratulations!
 
-You have learned the **basics of Docusaurus** and made some changes to the **initial template**.
+You have just learned the **basics of Docusaurus** and made some changes to the **initial template**.
 
 Docusaurus has **much more to offer**!
 
-Have 5 more minutes? Take a look at **[versioning](./manage-docs-versions.md)** and **[i18n](./translate-your-site.md)**.
+Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**.
+
+Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610)
 
 ## What's next?
 

packages/docusaurus-init/templates/classic/docs/tutorial-basics/create-a-blog-post.md

@@ -1,10 +1,12 @@
 ---
-title: Create a Blog Post
+sidebar_position: 3
 ---
 
+# Create a Blog Post
+
 Docusaurus creates a **page for each blog post**, but also a **blog index page**, a **tag system**, an **RSS** feed...
 
-## Create a Blog Post
+## Create your first Post
 
 Create a file at `blog/2021-02-28-greetings.md`:
 

packages/docusaurus-init/templates/classic/docs/tutorial-basics/create-a-document.md

@@ -0,0 +1,56 @@
+---
+sidebar_position: 2
+---
+
+# Create a Document
+
+Documents are **groups of pages** connected through:
+
+- a **sidebar**
+- **previous/next navigation**
+- **versioning**
+
+## Create your first Doc
+
+Create a markdown file at `docs/hello.md`:
+
+```md title="docs/hello.md"
+# Hello
+
+This is my **first Docusaurus document**!
+```
+
+A new document is now available at `http://localhost:3000/docs/hello`.
+
+## Configure the Sidebar
+
+Docusaurus automatically **creates a sidebar** from the `docs` folder.
+
+Add metadatas to customize the sidebar label and position:
+
+```diff title="docs/hello.md"
++ ---
++ sidebar_label: "Hi!"
++ sidebar_position: 3
++ ---
+
+
+# Hello
+
+This is my **first Docusaurus document**!
+```
+
+It is also possible to create your sidebar explicitly in `sidebars.js`:
+
+```diff title="sidebars.js"
+module.exports = {
+  tutorialSidebar: [
+    {
+      type: 'category',
+      label: 'Tutorial',
+-     items: [...],
++     items: ['hello'],
+    },
+  ],
+};
+```

packages/docusaurus-init/templates/classic/docs/tutorial-basics/create-a-page.md

@@ -1,14 +1,16 @@
 ---
-title: Create a Page
+sidebar_position: 1
 ---
 
-Add **Markdown or React** files to `src/pages` to create **standalone pages**:
+# Create a Page
+
+Add **Markdown or React** files to `src/pages` to create a **standalone page**:
 
 - `src/pages/index.js` -> `localhost:3000/`
 - `src/pages/foo.md` -> `localhost:3000/foo`
 - `src/pages/foo/bar.js` -> `localhost:3000/foo/bar`
 
-## Create a React Page
+## Create your first React Page
 
 Create a file at `src/pages/my-react-page.js`:
 
@@ -28,15 +30,11 @@ export default function MyReactPage() {
 
 A new page is now available at `http://localhost:3000/my-react-page`.
 
-## Create a Markdown Page
+## Create your first Markdown Page
 
 Create a file at `src/pages/my-markdown-page.md`:
 
 ```mdx title="src/pages/my-markdown-page.md"
----
-title: My Markdown page
----
-
 # My Markdown page
 
 This is a Markdown page

packages/docusaurus-init/templates/classic/docs/tutorial-basics/deploy-your-site.md

@@ -1,8 +1,12 @@
 ---
-title: Deploy your site
+sidebar_position: 5
 ---
 
-Docusaurus is a **static-site-generator** (also called [Jamstack](https://jamstack.org/)), and builds your site as **static HTML, JavaScript and CSS files**.
+# Deploy your site
+
+Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**).
+
+It builds your site as simple **static HTML, JavaScript and CSS files**.
 
 ## Build your site
 
@@ -12,7 +16,7 @@ Build your site **for production**:
 npm run build
 ```
 
-The static files are generated in the `build` directory.
+The static files are generated in the `build` folder.
 
 ## Deploy your site
 

packages/docusaurus-init/templates/classic/docs/tutorial-basics/markdown-features.mdx

@@ -1,20 +1,24 @@
 ---
-title: Markdown Features
+sidebar_position: 4
 ---
 
+# Markdown Features
+
 Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**.
 
 ## Front Matter
 
-Markdown documents have metadata at the very top called [Front Matter](https://jekyllrb.com/docs/front-matter/):
+Markdown documents have metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/):
 
-```md
+```text title="my-doc.md"
+// highlight-start
 ---
-id: my-doc
+id: my-doc-id
 title: My document title
 description: My document description
-sidebar_label: My doc
+slug: /my-custom-url
 ---
+// highlight-end
 
 ## Markdown heading
 

packages/docusaurus-init/templates/classic/docs/tutorial-extras/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Tutorial - Extras",
+  "position": 3
+}

packages/docusaurus-init/templates/classic/docs/tutorial-extras/manage-docs-versions.md

@@ -1,7 +1,9 @@
 ---
-title: Manage Docs Versions
+sidebar_position: 1
 ---
 
+# Manage Docs Versions
+
 Docusaurus can manage multiple versions of your docs.
 
 ## Create a docs version
@@ -12,7 +14,7 @@ Release a version 1.0 of your project:
 npm run docusaurus docs:version 1.0
 ```
 
-The `docs` directory is copied into `versioned_docs/version-1.0` and `versions.json` is created.
+The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created.
 
 Your docs now have 2 versions:
 

packages/docusaurus-init/templates/classic/docs/tutorial-extras/translate-your-site.md

@@ -1,7 +1,9 @@
 ---
-title: Translate your site
+sidebar_position: 2
 ---
 
+# Translate your site
+
 Let's translate `docs/getting-started.md` to French.
 
 ## Configure i18n
@@ -19,7 +21,7 @@ module.exports = {
 
 ## Translate a doc
 
-Copy the `docs/getting-started.md` file to the `i18n/fr` directory:
+Copy the `docs/getting-started.md` file to the `i18n/fr` folder:
 
 ```bash
 mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/
@@ -39,7 +41,7 @@ npm run start -- --locale fr
 
 Your localized site is accessible at `http://localhost:3000/fr/` and the `Getting Started` page is translated.
 
-:::warning
+:::caution
 
 In development, you can only use one locale at a same time.
 

packages/docusaurus-init/templates/classic/docusaurus.config.js

@@ -19,7 +19,7 @@ module.exports = {
       items: [
         {
           type: 'doc',
-          docId: 'getting-started',
+          docId: 'intro',
           position: 'left',
           label: 'Tutorial',
         },
@@ -38,8 +38,8 @@ module.exports = {
           title: 'Docs',
           items: [
             {
-              label: 'Getting Started',
-              to: '/docs/',
+              label: 'Tutorial',
+              to: '/docs/intro',
             },
           ],
         },

packages/docusaurus-init/templates/classic/sidebars.js

@@ -1,22 +1,26 @@
+/**
+ * Creating a sidebar enables you to:
+ - create an ordered group of docs
+ - render a sidebar for each doc of that group
+ - provide next/previous navigation
+
+ The sidebars can be generated from the filesystem, or explicitly defined here.
+
+ Create as many sidebars as you want.
+ */
+
 module.exports = {
-  tutorial: [
+  // By default, Docusaurus generates a sidebar from the docs folder structure
+  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],
+
+  // But you can create a sidebar manually
+  /*
+  tutorialSidebar: [
     {
       type: 'category',
-      label: 'Tutorial - Basics',
-      items: [
-        'getting-started',
-        'create-a-page',
-        'create-a-document',
-        'create-a-blog-post',
-        'markdown-features',
-        'deploy-your-site',
-        'congratulations',
-      ],
-    },
-    {
-      type: 'category',
-      label: 'Tutorial - Extras',
-      items: ['manage-docs-versions', 'translate-your-site'],
+      label: 'Tutorial',
+      items: ['hello'],
     },
   ],
+   */
 };

packages/docusaurus-init/templates/classic/src/components/HomepageFeatures.js

@@ -41,8 +41,10 @@ function Feature({Svg, title, description}) {
       <div className="text--center">
         <Svg className={styles.featureSvg} alt={title} />
       </div>
-      <h3>{title}</h3>
-      <p>{description}</p>
+      <div className="text--center padding-horiz--md">
+        <h3>{title}</h3>
+        <p>{description}</p>
+      </div>
     </div>
   );
 }

packages/docusaurus-init/templates/classic/src/pages/index.js

@@ -14,8 +14,10 @@ function HomepageHeader() {
         <h1 className="hero__title">{siteConfig.title}</h1>
         <p className="hero__subtitle">{siteConfig.tagline}</p>
         <div className={styles.buttons}>
-          <Link className="button button--secondary button--lg" to="/docs">
-            Get Started - Docusaurus Tutorial
+          <Link
+            className="button button--secondary button--lg"
+            to="/docs/intro">
+            Docusaurus Tutorial - 5min ⏱️
           </Link>
         </div>
       </div>