Sync

apps/docs/app/global.css

@@ -47,4 +47,4 @@
   --accent: 250 20% 38.3% !important;
   --muted-foreground: 230 80% 84% !important;
   --card: 230 40% 26.3% !important;
-}
+}

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

@@ -49,6 +49,7 @@ Force to open the folder by default.
 ### Multiple Page Trees
 
 Adding a `root` property in meta can mark your folder as a root folder.
+The nearest root folder of current page will be used as the root of page tree.
 
 ```json title="meta.json"
 {
@@ -57,8 +58,6 @@ Adding a `root` property in meta can mark your folder as a root folder.
 }
 ```
 
-The nearest root folder of current page will be used as the root of page tree.
-
 ## Meta
 
 Customize the display name, order of pages, or its items on the sidebar by
@@ -69,13 +68,15 @@ When a meta file presents, items are not included unless you have explicitly add
 ```json
 {
   "title": "Name of Folder",
-  "pages": ["guide", "components"] // filename of pages
+  "pages": ["guide", "components"]
 }
 ```
 
+> `pages` are the filenames of file
+
 ### Path
 
-The items of `pages` property can be a relative path to a page or folder.
+The items of `pages` property can be a relative path to a page or folder. File extensions are not required.
 
 ```json
 {

apps/docs/content/docs/ui/blocks/layout.mdx

@@ -5,14 +5,13 @@ description: The layout of documentation
 
 import { File, Files, Folder } from 'fumadocs-ui/components/files';
 
-The layout of documentation pages, it must be nested under the
-[Root Provider](/docs/ui/blocks/root-provider).
+The layout of documentation pages, it includes sidebar and navbar.
 
 > It is a server component, you should not reference it in a client component.
 
 ## Usage
 
-Wrap the children and pass your page tree to the component.
+Pass your page tree to the component.
 
 ```jsx
 import { DocsLayout } from 'fumadocs-ui/layout';
@@ -51,57 +50,111 @@ You can create a [Route Group](https://nextjs.org/docs/app/building-your-applica
   </Folder>
 </Files>
 
-### Links
+## Navbar
 
-You can display dropdown menus and links on navigation elements like navbar and sidebar.
+The navigation header provides common interactive elements.
 
-> They are displayed intelligently for best responsibility.
+```mdx
+<DocsLayout
+  nav={{ title: <Logo />, githubUrl: 'https://github.com/fuma-nama/fumadocs' }}
+/>
+```
+
+```json doc-gen:typescript
+{
+  "file": "./content/docs/ui/props.ts",
+  "name": "NavbarProps"
+}
+```
+
+## Sidebar
+
+Provide elements to navigate between pages.
 
 ```mdx
+<DocsLayout sidebar={{ footer: <ShareButton /> }} />
+```
+
+```json doc-gen:typescript
+{
+  "file": "./content/docs/ui/props.ts",
+  "name": "SidebarProps"
+}
+```
+
+## Links
+
+Navigation links displayed on every page.
+
+### Item
+
+A link to navigate to an URL, can be external.
+
+```mdx
+import { DocsLayout } from 'fumadocs-ui/layout';
+
 <DocsLayout
   links={[
     {
       icon: <BookIcon />,
       text: 'Blog',
       url: '/blog',
     },
+  ]}
+/>
+```
+
+To mark the item as active when browsing child pages like `/blog/post`, add set it as `nested-url`.
+
+```mdx
+import { DocsLayout } from 'fumadocs-ui/layout';
+
+<DocsLayout
+  links={[
     {
-      type: 'menu',
-      text: 'Guide',
-      items: [{ ... }],
+      icon: <BookIcon />,
+      text: 'Blog',
+      url: '/blog',
+      active: 'nested-url',
     },
   ]}
 />
 ```
 
-### Navbar
+### Secondary Item
 
-Customise the navbar element.
+Same as normal items, but are shown as icon buttons on the navbar.
 
 ```mdx
+import { DocsLayout } from 'fumadocs-ui/layout';
+
 <DocsLayout
-  nav={{ title: <Logo />, githubUrl: 'https://github.com/fuma-nama/fumadocs' }}
+  links={[
+    {
+      type: 'secondary',
+      icon: <BookIcon />,
+      text: 'Blog',
+      url: '/blog',
+    },
+  ]}
 />
 ```
 
-```json doc-gen:typescript
-{
-  "file": "./content/docs/ui/props.ts",
-  "name": "NavbarProps"
-}
-```
-
-### Sidebar
+### Dropdown Menu
 
-Customise the sidebar element.
+A dropdown menu containing multiple link items.
 
 ```mdx
-<DocsLayout sidebar={{ footer: <ShareButton /> }} />
-```
+import { DocsLayout } from 'fumadocs-ui/layout';
 
-```json doc-gen:typescript
-{
-  "file": "./content/docs/ui/props.ts",
-  "name": "SidebarProps"
-}
+<DocsLayout
+  links={[
+    {
+      icon: <BookIcon />,
+      type: 'menu',
+      text: 'Guide',
+      items: [{ ... }],
+    },
+  ]}
+/>
 ```

apps/docs/content/docs/ui/blocks/root-provider.mdx

@@ -22,30 +22,11 @@ export default function Layout({ children }) {
 }
 ```
 
-### Search Dialog
-
-You can customize the search dialog from the root provider.
+In addition, You can customize the search dialog from the root provider.
 
 ```json doc-gen:typescript
 {
   "file": "./content/docs/ui/props.ts",
   "name": "ProviderProps"
 }
 ```
-
-#### Custom Links
-
-Add custom link items to search dialog.
-
-```jsx
-<RootProvider
-  search={{
-    links: [
-      ['Home', '/'],
-      ['Docs', '/docs'],
-    ],
-  }}
->
-  ...
-</RootProvider>
-```

apps/docs/content/docs/ui/comparisons.mdx

@@ -10,15 +10,16 @@ Fumadocs, unlike the other frameworks, it expects you to write code and cooperat
 While most frameworks are configured with a configuration file, they are usually lack of flexibility when you attempted to complete something more advanced.
 You can't control how they render the page, neither the internal logic.
 
-Fumadocs has no magic, it just give you the utilities and a good-looking user interface.
-You are still using the features of Next.js App Router.
-You are still configuring Static Site Generation same as a normal Next.js application.
-Therefore, there is nothing new for Next.js developers, you are using it naturally.
-You don't need any _hacky_ ways anymore, as they are now parts of your software.
+**Fumadocs has no magic:** It gives you the utilities and a good-looking user interface.
+You are still using the features of Next.js App Router, configuring Static Site Generation same as a normal Next.js application.
+There is nothing new for Next.js developers, you can use it with confidence.
 
 For instance, in this docs, all index pages are rendered dynamically.
 Feel free to take a look at the source code of this documentation.
 
+**Opinionated on UI:** The only thing Fumadocs UI offers is **User Interface**, it is opinionated on UI for the best mobile responsibility and user experience.
+The design is regularly updated, and we are welcome for feedback about the UI.
+
 ## Nextra
 
 Fumadocs is highly inspired by Nextra. For example, the Routing Conventions. That is why

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

@@ -62,7 +62,7 @@ It will initialize a new fumadocs app, now you can start hacking!
 
 ### Enjoy!
 
-Now, create your first mdx file in the docs folder.
+Create your first mdx file in the docs folder.
 
 ```mdx title="content/docs/index.mdx"
 ---
@@ -78,7 +78,9 @@ Run the app in development mode and see http://localhost:3000/docs.
 npm run dev
 ```
 
-### FAQ
+## FAQ
+
+Some common questions you may encounter.
 
 <Accordions>
     <Accordion id='why-fumadocs-ui' title="Why Fumadocs UI?">
@@ -91,6 +93,21 @@ npm run dev
         - Built on App Router
         - Use it in an existing Next.js project, without refactoring anything.
     </Accordion>
+    <Accordion id='customise' title='How to Customise UI?'>
+
+        Fumadocs UI offers Themes, Blocks and Components.
+
+        The design system is built with Tailwind CSS, see [Themes](/docs/ui/theme).
+
+        Components are pre-built elements to enhance your documentation.
+        There are many pre-built components, and they are both customisable with exposed props like `style` and `className`.
+
+        Blocks are essential elements of a docs, providing navigation and basic functionality.
+        We provided many options to customise them, see the **Blocks** section of the docs.
+
+        Although the docs didn't explicitly mention, you can always style the elements with CSS selectors.
+
+    </Accordion>
     <Accordion id='fix-monorepo-styling' title="How to fix stylings not being applied in Monorepo?">
 
         Sometimes, `fumadocs-ui` is not installed in the workspace of your Tailwind CSS configuration file. (e.g. a monorepo setup).
@@ -151,10 +168,6 @@ npm run dev
 
 </Accordions>
 
-### Demo
-
-Open in [CodeSandbox](https://githubbox.com/fuma-nama/fumadocs-ui-template).
-
 ## Learn More
 
 New to here? Don't worry, we are welcome for your questions.

apps/docs/content/docs/ui/meta.json

@@ -4,6 +4,7 @@
   "pages": [
     "---Guide---",
     "index",
+    "comparisons",
     "...",
     "---Components---",
     "...components",
@@ -15,10 +16,9 @@
     "twoslash",
     "openapi",
     "museum",
-    "---Reference---",
-    "../headless/page-conventions",
-    "---Commands---",
+    "---Others---",
     "...commands",
+    "../headless/page-conventions",
     "[Vercel](https://vercel.com)"
   ]
 }