ContextWeave

Plan to Build the Documentation UI

The goal is to create a polished, navigable documentation section within the existing Next.js application that renders Markdown files from the docs/ directory.

1. Core Technology

  • Markdown Rendering: We will use react-markdown along with the remark-gfm plugin to parse the Markdown files and support GitHub Flavored Markdown (tables, etc.).
  • Syntax Highlighting: Code blocks will be styled using react-syntax-highlighter to ensure code examples are readable and match the site's aesthetic.
  • Data Fetching: We will use Node.js's fs and path modules within Next.js Server Components to read the documentation files and their directory structure from the server's file system.

2. File and Component Structure

A new app/docs/ route will be created with the following structure:

  • app/docs/layout.tsx: A new layout file specific to the documentation section. It will create a two-column view with a navigation sidebar.
  • app/docs/[...slug]/page.tsx: A dynamic route that catches all documentation URLs. The slug will correspond to the path of the Markdown file being requested.
  • components/DocsSidebar.tsx: A new component that displays the nested navigation menu for all documentation pages.
  • components/MarkdownRenderer.tsx: A dedicated component to handle the rendering of Markdown content, including styled code blocks and other elements.
  • lib/docs.ts: A new utility file containing helper functions to scan the docs/ directory, build a navigation tree, and retrieve individual document content.

3. Data and Rendering Flow

This diagram illustrates how a user request for a documentation page will be handled:

Loading diagram...

4. Implementation Steps

  1. Install Dependencies: Add react-markdown, remark-gfm, and react-syntax-highlighter to the project.
  2. Create Doc Utilities (lib/docs.ts): Implement functions to fetch the doc navigation tree and the content of a specific doc.
  3. Build Sidebar (components/DocsSidebar.tsx): Create the sidebar component that fetches the doc tree and renders it as a nested list of navigation links.
  4. Create Documentation Layout (app/docs/layout.tsx): Set up the two-column layout that includes the new DocsSidebar.
  5. Create Markdown Renderer (components/MarkdownRenderer.tsx): Configure react-markdown and react-syntax-highlighter. Customize the rendering of HTML elements to reuse existing UI components from components/ui/ for a consistent look.
  6. Create Dynamic Doc Page (app/docs/[...slug]/page.tsx): This page will fetch the Markdown content based on the URL slug and pass it to the MarkdownRenderer component.
  7. Update Header: Add a "Docs" link to the main Header component so users can easily find the new documentation section.
  8. Styling: Apply Tailwind CSS classes to all new components to ensure the design is consistent with the rest of the application.