Docs: Document docs page and layout

2026-10-26 10:55:57 +00:00 · 2023-07-29 23:09:55 +08:00
parent bd2db70c27
commit 484baed56c
2 changed files with 160 additions and 0 deletions
@@ -0,0 +1,86 @@
+---
+title: Docs Layout
+description: The layout of documentation pages
+---
+
+The layout of documentation pages, it must be nested under the Root Provider.
+
+## Usage
+
+Wrap the children and pass your page tree to the component.
+
+```tsx
+import { DocsLayout } from "next-docs-ui/layout";
+
+<DocsLayout tree={tree}>{children}</DocsLayout>;
+```
+
+| Prop             | Type                  | Description                        |
+| ---------------- | --------------------- | ---------------------------------- |
+| `navTitle`       | `string \| ReactNode` | Navbar title                       |
+| `tree`           | `TreeNode[]`          | The page tree                      |
+| `nav`            | `ReactNode \| false`  | Replace or disable default navbar  |
+| `githubUrl`      | `string`              | Github url displayed on the navbar |
+| `sidebarContent` | `ReactNode`           | Extra content on sidebar           |
+| `children`       | `ReactNode`           | -                                  |
+
+### Disabling Navbar
+
+It is common to share a navbar across all the pages (not just the docs layout). To achieve this, you may disable the default navbar by passing `false` to the `nav` prop.
+
+The default navbar is exported from `next-docs-ui/component`, you can add it to the root layout (under the root provider).
+
+<Accordion type="single" collapsible>
+<AccordionItem value="custom-navbar">
+<AccordionTrigger>Custom Navbar</AccordionTrigger>
+<AccordionContent>
+
+Example for custom navbar using Tailwind CSS.
+
+```tsx
+"use client";
+import { GithubIcon } from "lucide-react";
+import { usePathname } from "next/navigation";
+import { Nav as OriginalNav } from "next-docs-ui/components";
+import Link from "next/link";
+
+export function Nav() {
+    const pathname = usePathname();
+    const inDocs = pathname.startsWith("/docs/") || pathname === "/docs";
+
+    return (
+        <OriginalNav
+            enableSidebar={inDocs}
+            links={[
+                {
+                    icon: <GithubIcon className="w-5 h-5" />,
+                    href: "https://github.com/SonMooSans/next-docs",
+                    external: true,
+                },
+            ]}
+        >
+            <Link
+                href="/"
+                className="font-semibold whitespace-nowrap hover:text-muted-foreground"
+            >
+                Next Docs
+            </Link>
+        </OriginalNav>
+    );
+}
+```
+
+</AccordionContent>
+</AccordionItem>
+</Accordion>
+
+## Example
+
+```tsx title="app/docs/[[...slug]]/layout.tsx"
+import { ReactNode } from "react";
+import { DocsLayout } from "next-docs-ui/layout";
+
+export default function Layout({ children }: { children: ReactNode }) {
+    return <DocsLayout tree={tree}>{children}</DocsLayout>;
+}
+```
@@ -0,0 +1,74 @@
+---
+title: Docs Page
+description: A single page in your documentation
+---
+
+Page is the base element of a documentation, it includes Table of contents, Footer, and Breadcrumb.
+
+## Usage
+
+Pass the table of contents and page tree to the component.
+
+```tsx
+import { DocsPage } from "next-docs-ui/page";
+
+<DocsPage toc={toc} tree={tree}>
+    <MDXContent>...</MDXContent>
+</DocsPage>;
+```
+
+| Prop         | Type                       | Description                     |
+| ------------ | -------------------------- | ------------------------------- |
+| `tocContent` | `ReactNode \| undefined`   | Extra content to display in TOC |
+| `toc`        | `TableOfContents`          | -                               |
+| `footer`     | `FooterProps \| undefined` | -                               |
+| `children`   | `ReactNode`                | -                               |
+
+> **Note:** Footer is not enabled by default
+
+### Table of Contents
+
+It is a tree with all the headings in your document. For Markdown or MDX documents, You can parse TOC by using the [TOC Utility](/docs/headless/utils/get-toc).
+
+Here is an example using Contentlayer.
+
+```tsx
+const path = (params.slug ?? []).join("/");
+const page = allDocs.find((page) => page.slug === path);
+
+if (page == null) {
+    notFound();
+}
+
+const toc = await getTableOfContents(page.body.raw);
+```
+
+### Footer
+
+You need to manually enable it by passing the previous and next page to the `footer` prop.
+
+To get those pages, it's recommended to use the [Get Neighbours](/docs/headless/utils/find-neighbour) Utility.
+
+| Prop       | Type                                         | Description |
+| ---------- | -------------------------------------------- | ----------- |
+| `next`     | `{ name: string, url: string } \| undefined` | -           |
+| `previous` | `{ name: string, url: string } \| undefined` | -           |
+
+#### Example
+
+```tsx
+import { getPageUrl } from "next-docs-zeta/contentlayer";
+import { findNeighbour } from "next-docs-zeta/server";
+
+// Get the url of page
+const url = getPageUrl(page.slug.split("/"), "/docs");
+const neighbours = findNeighbour(tree, url);
+
+<DocsPage toc={toc} tree={tree} footer={neighbours}>
+    ...
+</DocsPage>;
+```
+
+### Breadcrumb
+
+For now, You can't control the behaviours of breadcrumb.