Documentation Updates (#79)

* Docs: Added Shadcn sidebar; added algorithm to automatically infer parents without needing to specify it.
* Extracted Markdoc compilation in a separate file
* Site Navigation: simplify nav by removing the border
* Docs Navigation: added TOC; improved layout on mobile

apps/web/app/(marketing)/_components/site-navigation.tsx

@@ -48,12 +48,8 @@ export function SiteNavigation() {
   return (
     <>
       <div className={'hidden items-center justify-center md:flex'}>
-        <NavigationMenu
-          className={
-            'rounded-full border border-gray-100 px-4 py-2 dark:border-primary/10'
-          }
-        >
-          <NavigationMenuList className={'space-x-4'}>
+        <NavigationMenu className={'px-4 py-2'}>
+          <NavigationMenuList className={'space-x-5'}>
             {NavItems}
           </NavigationMenuList>
         </NavigationMenu>

apps/web/app/(marketing)/blog/_components/html-renderer.module.css

@@ -1,25 +1,29 @@
+.HTML {
+  @apply text-secondary-foreground;
+}
+
 .HTML h1 {
-  @apply mt-14 text-4xl font-bold font-heading;
+  @apply mt-14 text-4xl font-semibold font-heading tracking-tight ;
 }
 
 .HTML h2 {
-  @apply mb-4 mt-12 text-2xl font-semibold lg:text-3xl font-heading;
+  @apply mb-4 mt-12 font-semibold text-2xl font-heading tracking-tight;
 }
 
 .HTML h3 {
-  @apply mt-10 text-2xl font-bold font-heading;
+  @apply mt-10 text-xl font-semibold font-heading tracking-tight;
 }
 
 .HTML h4 {
-  @apply mt-8 text-xl font-bold;
+  @apply mt-8 text-lg font-medium tracking-tight;
 }
 
 .HTML h5 {
-  @apply mt-6 text-lg font-semibold;
+  @apply mt-6 text-base font-medium tracking-tight;
 }
 
 .HTML h6 {
-  @apply mt-2 text-base font-medium;
+  @apply mt-2 text-sm font-normal tracking-tight;
 }
 
 /**
@@ -37,11 +41,11 @@ For more info: https://github.com/tailwindlabs/tailwindcss/issues/3258#issuecomm
 }
 
 .HTML p {
-  @apply mb-4 mt-2 text-base leading-7 text-muted-foreground;
+  @apply mb-4 mt-2 text-base leading-7;
 }
 
 .HTML li {
-  @apply relative my-1.5 text-base leading-7 text-muted-foreground;
+  @apply relative my-1.5 text-base leading-7;
 }
 
 .HTML ul > li:before {
@@ -93,5 +97,5 @@ For more info: https://github.com/tailwindlabs/tailwindcss/issues/3258#issuecomm
 }
 
 .HTML pre {
-  @apply my-6 text-sm text-current border p-6 rounded-lg;
+  @apply my-6 text-sm text-current border p-6 rounded-lg overflow-x-scroll;
 }

apps/web/app/(marketing)/docs/[...slug]/page.tsx

@@ -5,12 +5,17 @@ import { notFound } from 'next/navigation';
 import { ContentRenderer, createCmsClient } from '@kit/cms';
 import { If } from '@kit/ui/if';
 import { Separator } from '@kit/ui/separator';
+import { cn } from '@kit/ui/utils';
 
 import { withI18n } from '~/lib/i18n/with-i18n';
 
-import { SitePageHeader } from '../../_components/site-page-header';
+// styles
 import styles from '../../blog/_components/html-renderer.module.css';
+
+// local imports
 import { DocsCards } from '../_components/docs-cards';
+import { DocsTableOfContents } from '../_components/docs-table-of-contents';
+import { extractHeadingsFromJSX } from '../_lib/utils';
 
 const getPageBySlug = cache(pageLoader);
 
@@ -50,26 +55,35 @@ async function DocumentationPage({ params }: DocumentationPageProps) {
 
   const description = page?.description ?? '';
 
-  return (
-    <div className={'flex flex-1 flex-col'}>
-      <SitePageHeader
-        className={'lg:px-8'}
-        container={false}
-        title={page.title}
-        subtitle={description}
-      />
+  const headings = extractHeadingsFromJSX(
+    page.content as {
+      props: { children: React.ReactElement[] };
+    },
+  );
+
+  return (
+    <div className={'flex flex-col flex-1 space-y-4'}>
+      <div className={'flex'}>
+        <article className={cn(styles.HTML, 'space-y-12 container')}>
+          <section className={'flex flex-col space-y-4 pt-6'}>
+            <h1 className={'!my-0'}>{page.title}</h1>
+
+            <h2 className={'!mb-0 !font-normal text-muted-foreground'}>
+              {description}
+            </h2>
+          </section>
 
-      <div className={'flex flex-col space-y-4 py-6 lg:px-8'}>
-        <article className={styles.HTML}>
           <ContentRenderer content={page.content} />
         </article>
 
-        <If condition={page.children.length > 0}>
-          <Separator />
-
-          <DocsCards cards={page.children ?? []} />
-        </If>
+        <DocsTableOfContents data={headings} />
       </div>
+
+      <If condition={page.children.length > 0}>
+        <Separator />
+
+        <DocsCards cards={page.children ?? []} />
+      </If>
     </div>
   );
 }

apps/web/app/(marketing)/docs/_components/docs-nav-link.tsx

@@ -0,0 +1,26 @@
+'use client';
+
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
+
+import { SidebarMenuButton, SidebarMenuItem } from '@kit/ui/shadcn-sidebar';
+import { cn, isRouteActive } from '@kit/ui/utils';
+
+export function DocsNavLink({ label, url }: { label: string; url: string }) {
+  const currentPath = usePathname();
+  const isCurrent = isRouteActive(url, currentPath, true);
+
+  return (
+    <SidebarMenuItem>
+      <SidebarMenuButton
+        asChild
+        isActive={isCurrent}
+        className={cn('border-l-3 transition-background !font-normal')}
+      >
+        <Link href={url}>
+          <span className="block max-w-full truncate">{label}</span>
+        </Link>
+      </SidebarMenuButton>
+    </SidebarMenuItem>
+  );
+}

apps/web/app/(marketing)/docs/_components/docs-navigation.tsx

@@ -1,192 +1,68 @@
-'use client';
-
-import { useEffect, useMemo, useState } from 'react';
-
-import Link from 'next/link';
-import { usePathname } from 'next/navigation';
-
-import { Menu } from 'lucide-react';
-
 import { Cms } from '@kit/cms';
-import { isBrowser } from '@kit/shared/utils';
-import { Button } from '@kit/ui/button';
-import { If } from '@kit/ui/if';
-import { cn, isRouteActive } from '@kit/ui/utils';
+import {
+  Sidebar,
+  SidebarGroup,
+  SidebarGroupContent,
+  SidebarMenu,
+  SidebarMenuSub,
+} from '@kit/ui/shadcn-sidebar';
 
-function DocsNavLink({
-  label,
-  url,
-  level,
-  activePath,
-}: {
-  label: string;
-  url: string;
-  level: number;
-  activePath: string;
-}) {
-  const isCurrent = isRouteActive(url, activePath, true);
-  const isFirstLevel = level === 0;
+import { DocsNavLink } from '~/(marketing)/docs/_components/docs-nav-link';
 
-  return (
-    <Button
-      className={cn('w-full shadow-none', {
-        ['font-normal']: !isFirstLevel,
-      })}
-      variant={isCurrent ? 'secondary' : 'ghost'}
-    >
-      <Link
-        className="flex h-full max-w-full grow items-center space-x-2"
-        href={url}
-      >
-        <span className="block max-w-full truncate">{label}</span>
-      </Link>
-    </Button>
-  );
-}
+import { FloatingDocumentationNavigation } from './floating-docs-navigation';
 
-function Node({
-  node,
-  level,
-  activePath,
-}: {
-  node: Cms.ContentItem;
-  level: number;
-  activePath: string;
-}) {
+function Node({ node, level }: { node: Cms.ContentItem; level: number }) {
   const pathPrefix = `/docs`;
   const url = `${pathPrefix}/${node.slug}`;
 
   return (
     <>
-      <DocsNavLink
-        label={node.title}
-        url={url}
-        level={level}
-        activePath={activePath}
-      />
+      <DocsNavLink label={node.title} url={url} />
 
       {(node.children ?? []).length > 0 && (
-        <Tree
-          pages={node.children ?? []}
-          level={level + 1}
-          activePath={activePath}
-        />
+        <Tree pages={node.children ?? []} level={level + 1} />
       )}
     </>
   );
 }
 
-function Tree({
-  pages,
-  level,
-  activePath,
-}: {
-  pages: Cms.ContentItem[];
-  level: number;
-  activePath: string;
-}) {
+function Tree({ pages, level }: { pages: Cms.ContentItem[]; level: number }) {
+  if (level === 0) {
+    return pages.map((treeNode, index) => (
+      <SidebarGroup key={index}>
+        <SidebarGroupContent>
+          <SidebarMenu>
+            <Node key={index} node={treeNode} level={level} />
+          </SidebarMenu>
+        </SidebarGroupContent>
+      </SidebarGroup>
+    ));
+  }
+
   return (
-    <div
-      className={cn('w-full space-y-1', {
-        ['pl-3']: level > 0,
-      })}
-    >
+    <SidebarMenuSub>
       {pages.map((treeNode, index) => (
-        <Node
-          key={index}
-          node={treeNode}
-          level={level}
-          activePath={activePath}
-        />
+        <Node key={index} node={treeNode} level={level} />
       ))}
-    </div>
+    </SidebarMenuSub>
   );
 }
 
 export function DocsNavigation({ pages }: { pages: Cms.ContentItem[] }) {
-  const activePath = usePathname();
-
   return (
     <>
-      <aside
-        style={{
-          height: `calc(100vh - 64px)`,
-        }}
-        className="sticky top-2 hidden w-80 shrink-0 overflow-y-auto border-r p-4 lg:flex"
+      <Sidebar
+        variant={'ghost'}
+        className={'sticky'}
       >
-        <Tree pages={pages} level={0} activePath={activePath} />
-      </aside>
+        <Tree pages={pages} level={0} />
+      </Sidebar>
 
       <div className={'lg:hidden'}>
-        <FloatingDocumentationNavigation
-          pages={pages}
-          activePath={activePath}
-        />
+        <FloatingDocumentationNavigation>
+          <Tree pages={pages} level={0} />
+        </FloatingDocumentationNavigation>
       </div>
     </>
   );
 }
-
-function FloatingDocumentationNavigation({
-  pages,
-  activePath,
-}: React.PropsWithChildren<{
-  pages: Cms.ContentItem[];
-  activePath: string;
-}>) {
-  const body = useMemo(() => {
-    return isBrowser() ? document.body : null;
-  }, []);
-
-  const [isVisible, setIsVisible] = useState(false);
-
-  const enableScrolling = (element: HTMLElement) =>
-    (element.style.overflowY = '');
-
-  const disableScrolling = (element: HTMLElement) =>
-    (element.style.overflowY = 'hidden');
-
-  // enable/disable body scrolling when the docs are toggled
-  useEffect(() => {
-    if (!body) {
-      return;
-    }
-
-    if (isVisible) {
-      disableScrolling(body);
-    } else {
-      enableScrolling(body);
-    }
-  }, [isVisible, body]);
-
-  // hide docs when navigating to another page
-  useEffect(() => {
-    setIsVisible(false);
-  }, [activePath]);
-
-  const onClick = () => {
-    setIsVisible(!isVisible);
-  };
-
-  return (
-    <>
-      <If condition={isVisible}>
-        <div
-          className={
-            'fixed left-0 top-0 z-10 h-screen w-full p-4' +
-            ' flex flex-col space-y-4 overflow-auto bg-white dark:bg-background'
-          }
-        >
-          <Tree pages={pages} level={0} activePath={activePath} />
-        </div>
-      </If>
-
-      <Button
-        className={'fixed bottom-5 right-5 z-10 h-16 w-16 rounded-full'}
-        onClick={onClick}
-      >
-        <Menu className={'h-8'} />
-      </Button>
-    </>
-  );
-}

apps/web/app/(marketing)/docs/_components/docs-table-of-contents.tsx

@@ -0,0 +1,51 @@
+'use client';
+
+import Link from 'next/link';
+
+interface NavItem {
+  text: string;
+  level: number;
+  href: string;
+  children: NavItem[];
+}
+
+export function DocsTableOfContents(props: { data: NavItem[] }) {
+  const navData = props.data;
+
+  return (
+    <div className="lg:block hidden sticky z-10 bg-background min-w-[14em] border-l p-4 inset-y-0 h-svh">
+      <ol
+        role="list"
+        className="relative text-sm text-gray-600 dark:text-gray-400"
+      >
+        {navData.map((item) => (
+          <li key={item.href} className="group/item relative mt-3 first:mt-0">
+            <a
+              href={item.href}
+              className="block transition-colors hover:text-gray-950 dark:hover:text-white [&_*]:[font:inherit]"
+            >
+              {item.text}
+            </a>
+            {item.children && (
+              <ol role="list" className="relative mt-3 pl-4">
+                {item.children.map((child) => (
+                  <li
+                    key={child.href}
+                    className="group/subitem relative mt-3 first:mt-0"
+                  >
+                    <Link
+                      href={child.href}
+                      className="block transition-colors hover:text-gray-950 dark:hover:text-white [&_*]:[font:inherit]"
+                    >
+                      {child.text}
+                    </Link>
+                  </li>
+                ))}
+              </ol>
+            )}
+          </li>
+        ))}
+      </ol>
+    </div>
+  );
+}

apps/web/app/(marketing)/docs/_components/floating-docs-navigation.tsx

@@ -0,0 +1,73 @@
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+
+import { usePathname } from 'next/navigation';
+
+import { Menu } from 'lucide-react';
+
+import { isBrowser } from '@kit/shared/utils';
+import { Button } from '@kit/ui/button';
+import { If } from '@kit/ui/if';
+
+export function FloatingDocumentationNavigation(
+  props: React.PropsWithChildren,
+) {
+  const activePath = usePathname();
+
+  const body = useMemo(() => {
+    return isBrowser() ? document.body : null;
+  }, []);
+
+  const [isVisible, setIsVisible] = useState(false);
+
+  const enableScrolling = (element: HTMLElement) =>
+    (element.style.overflowY = '');
+
+  const disableScrolling = (element: HTMLElement) =>
+    (element.style.overflowY = 'hidden');
+
+  // enable/disable body scrolling when the docs are toggled
+  useEffect(() => {
+    if (!body) {
+      return;
+    }
+
+    if (isVisible) {
+      disableScrolling(body);
+    } else {
+      enableScrolling(body);
+    }
+  }, [isVisible, body]);
+
+  // hide docs when navigating to another page
+  useEffect(() => {
+    setIsVisible(false);
+  }, [activePath]);
+
+  const onClick = () => {
+    setIsVisible(!isVisible);
+  };
+
+  return (
+    <>
+      <If condition={isVisible}>
+        <div
+          className={
+            'fixed left-0 top-0 z-10 h-screen w-full p-4' +
+            ' flex flex-col space-y-4 overflow-auto bg-white dark:bg-background'
+          }
+        >
+          {props.children}
+        </div>
+      </If>
+
+      <Button
+        className={'fixed bottom-5 right-5 z-10 h-16 w-16 rounded-full'}
+        onClick={onClick}
+      >
+        <Menu className={'h-8'} />
+      </Button>
+    </>
+  );
+}

apps/web/app/(marketing)/docs/_lib/utils.ts

@@ -0,0 +1,136 @@
+import { Cms } from '@kit/cms';
+
+interface HeadingNode {
+  text: string;
+  level: number;
+  href: string;
+  children: HeadingNode[];
+}
+
+/**
+ * @name buildDocumentationTree
+ * @description Build a tree structure for the documentation pages.
+ * @param pages
+ */
+export function buildDocumentationTree(pages: Cms.ContentItem[]) {
+  const tree: Cms.ContentItem[] = [];
+
+  pages.forEach((page) => {
+    if (page.parentId) {
+      const parent = pages.find((item) => item.slug === page.parentId);
+
+      if (!parent) {
+        return;
+      }
+
+      if (!parent.children) {
+        parent.children = [];
+      }
+
+      parent.children.push(page);
+
+      // sort children by order
+      parent.children.sort((a, b) => a.order - b.order);
+    } else {
+      tree.push(page);
+    }
+  });
+
+  return tree.sort((a, b) => a.order - b.order);
+}
+
+/**
+ * @name extractHeadingsFromJSX
+ * @description Extract headings from JSX. This is used to generate the table of contents for the documentation pages.
+ * @param jsx
+ */
+export function extractHeadingsFromJSX(jsx: {
+  props: { children: React.ReactElement[] };
+}) {
+  const headings: HeadingNode[] = [];
+  let currentH2: HeadingNode | null = null;
+
+  function getTextContent(
+    children: React.ReactElement[] | string | React.ReactElement,
+  ): string {
+    if (typeof children === 'string') {
+      return children;
+    }
+
+    if (Array.isArray(children)) {
+      return children.map((child) => getTextContent(child)).join('');
+    }
+
+    if (
+      (
+        children.props as {
+          children: React.ReactElement;
+        }
+      ).children
+    ) {
+      return getTextContent((children.props as { children: React.ReactElement }).children);
+    }
+
+    return '';
+  }
+
+  jsx.props.children.forEach((node) => {
+    if (!node || typeof node !== 'object' || !('type' in node)) {
+      return;
+    }
+
+    const nodeType = node.type as string;
+
+    const text = getTextContent(
+      (
+        node.props as {
+          children: React.ReactElement[];
+        }
+      ).children,
+    );
+
+    if (nodeType === 'h1') {
+      const slug = generateSlug(text);
+
+      headings.push({
+        text,
+        level: 1,
+        href: `#${slug}`,
+        children: [],
+      });
+    } else if (nodeType === 'h2') {
+      const slug = generateSlug(text);
+
+      currentH2 = {
+        text,
+        level: 2,
+        href: `#${slug}`,
+        children: [],
+      };
+
+      if (headings.length > 0) {
+        headings[headings.length - 1]!.children.push(currentH2);
+      } else {
+        headings.push(currentH2);
+      }
+    } else if (nodeType === 'h3' && currentH2) {
+      const slug = generateSlug(text);
+
+      currentH2.children.push({
+        text,
+        level: 3,
+        href: `#${slug}`,
+        children: [],
+      });
+    }
+  });
+
+  return headings;
+}
+
+function generateSlug(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/(^-|-$)/g, '');
+}

apps/web/app/(marketing)/docs/layout.tsx

@@ -1,56 +1,24 @@
-import { Cms } from '@kit/cms';
+import { SidebarProvider } from '@kit/ui/shadcn-sidebar';
 
 import { createI18nServerInstance } from '~/lib/i18n/i18n.server';
 
 // local imports
 import { DocsNavigation } from './_components/docs-navigation';
 import { getDocs } from './_lib/server/docs.loader';
+import { buildDocumentationTree } from './_lib/utils';
 
 async function DocsLayout({ children }: React.PropsWithChildren) {
   const { resolvedLanguage } = await createI18nServerInstance();
-  const pages = await getDocs(resolvedLanguage);
+  const docs = await getDocs(resolvedLanguage);
+  const tree = buildDocumentationTree(docs);
 
   return (
-    <div className={'md:container flex'}>
-      <DocsNavigation pages={buildDocumentationTree(pages)} />
+    <SidebarProvider className={'lg:container'}>
+      <DocsNavigation pages={tree} />
 
       {children}
-    </div>
+    </SidebarProvider>
   );
 }
 
 export default DocsLayout;
-
-// we want to place all the children under their parent
-// based on the property parentId
-function buildDocumentationTree(pages: Cms.ContentItem[]) {
-  const tree: Cms.ContentItem[] = [];
-  const map: Record<string, Cms.ContentItem> = {};
-
-  pages.forEach((page) => {
-    map[page.id] = page;
-  });
-
-  pages.forEach((page) => {
-    if (page.parentId) {
-      const parent = map[page.parentId];
-
-      if (!parent) {
-        return;
-      }
-
-      if (!parent.children) {
-        parent.children = [];
-      }
-
-      parent.children.push(page);
-
-      // sort children by order
-      parent.children.sort((a, b) => a.order - b.order);
-    } else {
-      tree.push(page);
-    }
-  });
-
-  return tree.sort((a, b) => a.order - b.order);
-}

apps/web/app/(marketing)/docs/loading.tsx

@@ -0,0 +1,3 @@
+import { GlobalLoader } from '@kit/ui/global-loader';
+
+export default GlobalLoader;

apps/web/content/documentation/authentication/configuration.mdoc

@@ -2,8 +2,7 @@
 title: "Configuration"
 description: "Learn how authentication works in MakerKit and how to configure it."
 publishedAt: 2024-04-11
-order: 0
-parent: "authentication/authentication"
+order: 1
 status: "published"
 ---
 

apps/web/content/documentation/getting-started/installing-dependencies.mdoc

@@ -2,7 +2,6 @@
 title: "Installing Dependencies"
 description: "Learn how to install dependencies for your project."
 publishedAt: 2024-04-11
-parent: "getting-started/getting-started"
 order: 0
 status: "published"
 ---