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
2025-06-27 06:57:57 +02:00 · 2021-04-15 16:20:11 +02:00 · 2021-04-15 16:20:11 +02:00 · db79d462ab
commit db79d462ab
parent 836f92708a
67 changed files with 2887 additions and 306 deletions
--- a/packages/docusaurus-init/templates/classic/docs/tutorial-basics/markdown-features.mdx
+++ b/packages/docusaurus-init/templates/classic/docs/tutorial-basics/markdown-features.mdx
@ -0,0 +1,144 @@
+---
+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 top called [Front Matter](https://jekyllrb.com/docs/front-matter/):
+
+```text title="my-doc.md"
+// highlight-start
+---
+id: my-doc-id
+title: My document title
+description: My document description
+slug: /my-custom-url
+---
+// highlight-end
+
+## Markdown heading
+
+Markdown text with [links](./hello.md)
+```
+
+## Links
+
+Regular Markdown links are supported, using url paths or relative file paths.
+
+```md
+Let's see how to [Create a page](/create-a-page).
+```
+
+```md
+Let's see how to [Create a page](./create-a-page.md).
+```
+
+**Result:** Let's see how to [Create a page](./create-a-page.md).
+
+## Images
+
+Regular Markdown images are supported.
+
+Add an image at `static/img/docusaurus.png` and display it in Markdown:
+
+```md
+![Docusaurus logo](/img/docusaurus.png)
+```
+
+![Docusaurus logo](/img/docusaurus.png)
+
+## Code Blocks
+
+Markdown code blocks are supported with Syntax highlighting.
+
+    ```jsx title="src/components/HelloDocusaurus.js"
+    function HelloDocusaurus() {
+        return (
+            <h1>Hello, Docusaurus!</h1>
+        )
+    }
+    ```
+
+```jsx title="src/components/HelloDocusaurus.js"
+function HelloDocusaurus() {
+  return <h1>Hello, Docusaurus!</h1>;
+}
+```
+
+## Admonitions
+
+Docusaurus has a special syntax to create admonitions and callouts:
+
+    :::tip My tip
+
+    Use this awesome feature option
+
+    :::
+
+    :::danger Take care
+
+    This action is dangerous
+
+    :::
+
+:::tip My tip
+
+Use this awesome feature option
+
+:::
+
+:::danger Take care
+
+This action is dangerous
+
+:::
+
+## MDX and React Components
+
+[MDX](https://mdxjs.com/) can make your documentation more **interactive** and allows using any **React components inside Markdown**:
+
+```jsx
+export const Highlight = ({children, color}) => (
+  <span
+    style={{
+      backgroundColor: color,
+      borderRadius: '20px',
+      color: '#fff',
+      padding: '10px',
+      cursor: 'pointer',
+    }}
+    onClick={() => {
+      alert(`You clicked the color ${color} with label ${children}`)
+    }}>
+    {children}
+  </span>
+);
+
+This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
+
+This is <Highlight color="#1877F2">Facebook blue</Highlight> !
+```
+
+export const Highlight = ({children, color}) => (
+  <span
+    style={{
+      backgroundColor: color,
+      borderRadius: '20px',
+      color: '#fff',
+      padding: '10px',
+      cursor: 'pointer',
+    }}
+    onClick={() => {
+      alert(`You clicked the color ${color} with label ${children}`);
+    }}>
+    {children}
+  </span>
+);
+
+This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !
+
+This is <Highlight color="#1877F2">Facebook blue</Highlight> !