Docs: rewrite navigation guide

Author: fuma-nama

apps/docs/content/docs/headless/page-conventions.mdx

@@ -5,8 +5,9 @@ description: A shared convention for organizing your documents
 
 ## Overview
 
-On Fumadocs MDX, or other file-system based content sources, the sidebar items (page tree) are generated from your file structure.
-This is similar to Next.js's file system based routing.
+Page slugs and sidebar items (page tree) are generated from your file structure, similar to file-system based routing in Next.js.
+
+> This only applies for file-system based content sources, such as Fumadocs MDX.
 
 ## File
 
@@ -68,11 +69,11 @@ To create a folder group, wrap the folder name in parentheses.
 
 ## Meta
 
-Customize a folder by creating a `meta.json` file in the folder.
+Customize a folder by creating a `meta.json` file in a folder under content folder.
 
 ### Display Name
 
-```json
+```json title="meta.json"
 {
   "title": "Name of Folder"
 }
@@ -95,7 +96,7 @@ Control the order of items.
 
 When a meta file is present, items are not included unless you have explicitly added them to `pages`.
 
-```json
+```json title="meta.json"
 {
   "title": "Name of Folder",
   "pages": ["guide", "components"]
@@ -112,7 +113,7 @@ When a meta file is present, items are not included unless you have explicitly a
 
 The items of `pages` can also be a relative path to a page or folder, no file extensions needed.
 
-```json
+```json title="meta.json"
 {
   "title": "Name of Folder",
   "pages": ["../headless/page"]
@@ -134,7 +135,7 @@ Force to open the folder by default.
 
 You can define a separator in meta by adding a item surrounded with `---`.
 
-```json
+```json title="meta.json"
 {
   "title": "Name of Folder",
   "pages": ["---Separator---"]
@@ -149,7 +150,7 @@ Add a Rest (`...`) item to automatically add and sort remaining page items alpha
   Index pages won't be included, you must specify the order of `index`.
 </Callout>
 
-```json
+```json title="meta.json"
 {
   "title": "Folder",
   "pages": ["guide", "..."]
@@ -158,7 +159,7 @@ Add a Rest (`...`) item to automatically add and sort remaining page items alpha
 
 You can also sort items reversely.
 
-```json
+```json title="meta.json"
 {
   "title": "Folder",
   "pages": ["guide", "z...a"]
@@ -169,7 +170,7 @@ You can also sort items reversely.
 
 In conjunction with the Rest item (`...`), you can use `!name` to exclude an item from the rest.
 
-```json
+```json title="meta.json"
 {
   "title": "Folder",
   "pages": ["...", "!hide-this-page"]
@@ -180,7 +181,7 @@ In conjunction with the Rest item (`...`), you can use `!name` to exclude an ite
 
 You can extract the items from a folder with `...folder_name`.
 
-```json
+```json title="meta.json"
 {
   "title": "Folder",
   "pages": ["guide", "...folder"]
@@ -191,7 +192,7 @@ You can extract the items from a folder with `...folder_name`.
 
 Use the syntax `[Text](url)` to insert links.
 
-```json
+```json title="meta.json"
 {
   "title": "Folder",
   "pages": ["index", "[Vercel](https://vercel.com)"]
@@ -200,7 +201,7 @@ Use the syntax `[Text](url)` to insert links.
 
 You can add an icon too.
 
-```json
+```json title="meta.json"
 {
   "title": "Folder",
   "pages": ["index", "[Triangle][Vercel](https://vercel.com)"]
@@ -215,13 +216,13 @@ You can add an [`icon` handler](/docs/headless/source-api#icons) to `loader()`.
 
 ## Root Folder
 
-<div className='max-w-[360px] mx-auto'>
+Marks the folder as a root folder.
 
-![Sidebar Tabs](/docs/sidebar-tabs.png)
+<Callout title='Fumadocs UI'>
 
-</div>
+    Fumadocs UI renders root folders as [Sidebar Tabs](/docs/ui/navigation/sidebar#sidebar-tabs), which allows user to switch between them.
 
-Adding a `root` property in meta file can mark your folder as a **root**.
+</Callout>
 
 ```json title="meta.json"
 {
@@ -231,7 +232,7 @@ Adding a `root` property in meta file can mark your folder as a **root**.
 }
 ```
 
-When the user is browsing a page under a root folder, only the child items of the folder will be visible.
+Only items in the current root folder will be considered.
 
 For example, when you are in a root folder called `framework`, the other folders (e.g. `headless`) are not shown on the sidebar and other navigation elements.
 
@@ -245,13 +246,7 @@ For example, when you are in a root folder called `framework`, the other folders
   </Folder>
 </Files>
 
-<Callout title='Fumadocs UI'>
-
-    Fumadocs UI renders root folders as Sidebar Tabs, which allows user to switch between them.
 
-    You can customise it via [`sidebar.tabs`](/docs/ui/layouts/docs#sidebar-tabs) in Docs Layout.
-
-</Callout>
 
 ### Index Pages
 

apps/docs/content/docs/ui/index.mdx

@@ -47,11 +47,11 @@ A command line tool to install UI components and automate things, useful for cus
 
 **Markdown/MDX:** Markdown is a markup language for creating formatted text. Fumadocs supports Markdown and MDX (superset of Markdown) out-of-the-box.
 
-Some basic knowledge of Next.js App Router would be useful for further customisations.
+Although not required, some basic knowledge of Next.js App Router would be useful for further customisations.
 
 ## Automatic Installation
 
-Create a new app with `create-fumadocs-app`.
+A minimum version of Node.js 18 required, note that Node.js 23.1 might have problems with Next.js production build.
 
 <Tabs groupId='package-manager' persist items={['npm', 'pnpm', 'yarn', 'bun']}>
 
@@ -73,10 +73,7 @@ bun create fumadocs-app
 
 </Tabs>
 
-> Node.js 18 or above required, Node.js 23.1 might have problems with Next.js production build.
-
-It will initialize a new fumadocs app.
-Now you can start hacking!
+It will initialize a new fumadocs app. Now you can start hacking!
 
 <Callout title='From Existing Codebase?'>
 
@@ -115,39 +112,41 @@ In the project, you can see:
 | `app/docs`                | The documentation layout and pages.                    |
 | `app/api/search/route.ts` | The Route Handler for search.                          |
 
-### Customise Content
+### Writing Content
+
+For authoring docs, make sure to read:
+
+<Cards>
+  <Card href="/docs/ui/markdown" title="Markdown">
+    Fumadocs has some additional features for authoring content too.
+  </Card>
+  <Card href="/docs/ui/navigation" title="Navigation">
+    Learn how to customise navigation links/sidebar items.
+  </Card>
+</Cards>
+
+### Content Source
 
 Content source handles all your content, like compiling Markdown files and validating frontmatter.
 
 <Tabs items={['Fumadocs MDX', 'Custom Source']}>
 
     <Tab value='Fumadocs MDX'>
 
-Read the [Introduction](/docs/mdx) to learn how it handles your content.
+        Read the [Introduction](/docs/mdx) to learn how it handles your content.
 
-A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
+        A `source.config.ts` config file has been included, you can customise different options like frontmatter schema.
 
     </Tab>
 
     <Tab value='Custom Source'>
 
-Fumadocs is not Markdown-exclusive. For other sources like Sanity, you can build a [custom content source](/docs/headless/custom-source).
+        Fumadocs is not Markdown-exclusive. For other sources like Sanity, you can build a [custom content source](/docs/headless/custom-source).
 
     </Tab>
 
 </Tabs>
 
-### Writing Content
-
-<Cards>
-  <Card href="/docs/ui/markdown" title="Markdown">
-    Fumadocs has some additional features for authoring content too.
-  </Card>
-  <Card href="/docs/ui/page-conventions" title="Organizing Pages">
-    Learn how to organize your content.
-  </Card>
-</Cards>
-
 ### Customise UI
 
 See [Customisation Guide](/docs/ui/customisation).
@@ -232,6 +231,17 @@ will replace the `/docs` page with your `page.tsx`.
 
     </Accordion>
 
+    <Accordion id='multi-versions' title="How to implement docs with multi-version?">
+        Use a separate deployment for each version.
+
+        On Vercel, this can be done by creating another branch for a specific version on your GitHub repository.
+        To link to the sites of other versions, use the Links API or a custom navigation component.
+    </Accordion>
+
+    <Accordion id='multi-docs' title="How to implement multi-docs?">
+        We recommend to use [Sidebar Tabs](/docs/ui/navigation/sidebar#sidebar-tabs).
+    </Accordion>
+
 </Accordions>
 
 ## Learn More

apps/docs/content/docs/ui/layouts/docs.mdx

@@ -45,62 +45,75 @@ import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
 <AutoTypeTable path="./content/docs/ui/props.ts" name="SidebarProps" />
 
-## Sidebar Tabs
+### Sidebar Tabs
 
-A navigation component to switch between root folders.
+See [Navigation Guide](/docs/ui/navigation/sidebar#sidebar-tabs) for usages.
 
-<div className='max-w-[360px] mx-auto'>
+#### Decoration
 
-![Sidebar Tabs](/docs/sidebar-tabs.png)
-
-</div>
-
-You can add items from the page tree (see [Root Folder](/docs/ui/page-conventions#root-folder)), or specify them explicitly:
+Change the icon/styles of tabs.
 
 ```tsx
 import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
 <DocsLayout
   sidebar={{
-    tabs: [
-      {
-        title: 'Test',
-        description: 'Test Tab',
-        url: '/docs/test',
-      },
-    ],
+    tabs: {
+      transform: (option, node) => ({
+        ...option,
+        icon: 'my icon',
+      }),
+    },
   }}
 />;
 ```
 
-Set it to `false` to disable:
+## Nav
 
-```tsx
-import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+A mobile-only navbar, we recommend to customise it from `baseOptions`.
+
+<div className='max-w-[460px] mx-auto'>
 
-<DocsLayout sidebar={{ tabs: false }} />;
+![Docs Nav](/docs/docs-nav.png)
+
+</div>
+
+```tsx
+import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
+
+export const baseOptions: BaseLayoutProps = {
+  githubUrl: 'https://github.com/fuma-nama/fumadocs',
+  nav: {
+    title: 'My App',
+  },
+};
 ```
 
-### Decoration
+<AutoTypeTable
+    path="./content/docs/ui/props.ts"
+    type="Omit<NavbarProps, 'children'>"
+/>
 
-Change the icon/styles of tabs.
+### Transparent Mode
+
+To make the navbar background transparent, you can configure transparent mode.
 
 ```tsx
-import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
-<DocsLayout
-  sidebar={{
-    tabs: {
-      transform: (option, node) => ({
-        ...option,
-        icon: 'my icon',
-      }),
-    },
-  }}
-/>;
+export const baseOptions: BaseLayoutProps = {
+  nav: {
+    transparentMode: 'top',
+  },
+};
 ```
 
-<include cwd>./content/shared/shared.nav.mdx</include>
+| Mode     | Description                         |
+| -------- | ----------------------------------- |
+| `always` | Always use a transparent background |
+| `top`    | When at the top of page             |
+| `none`   | Disable transparent background (default)      |
+
 
 ### Replace Navbar
 

apps/docs/content/docs/ui/navigation/index.mdx

@@ -0,0 +1,5 @@
+---
+title: Navigation
+description: Configure navigation in your Fumadocs app.
+index: true
+---