docs set up #2
docs set up #2
Conversation
WalkthroughThe PR introduces MDX documentation support to a Next.js 15 project by configuring MDX in the Next.js config, defining custom component renderers, adding tooling dependencies, implementing a responsive documentation layout with sidebar navigation, and applying syntax highlighting styles. Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant Navbar
participant DocsLayout
participant DocsSidebar
participant MDXPage
participant useMDXComponents
User->>Navbar: Click Docs button
Navbar->>DocsLayout: Navigate to /docs route
DocsLayout->>DocsSidebar: Render sidebar with routes
DocsSidebar->>DocsSidebar: Determine active item from pathname
DocsSidebar->>User: Display navigation (desktop/mobile)
User->>MDXPage: Click doc link (e.g., Components)
MDXPage->>useMDXComponents: Render MDX content
useMDXComponents->>useMDXComponents: Apply custom renderers<br/>(h1, code, img, table, etc.)
useMDXComponents->>User: Display styled documentation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🧹 Nitpick comments (3)
src/styles/globals.css (1)
128-154: Remove redundantcounter-resetdeclaration.The
counter-reset: lineis declared twice—once on line 129 for allcodeelements and again on line 153 specifically forcode[data-line-numbers]. Since line numbers only apply to elements with thedata-line-numbersattribute, the first declaration is unnecessary.Apply this diff to remove the redundancy:
-code { - counter-reset: line; -} - code[data-theme*=" "], code[data-theme*=" "] span { color: var(--shiki-light);src/app/docs/_components/sidebar.tsx (2)
12-27: Consider extracting navigation config to separate file.As the documentation grows, the
docsRoutesconfiguration may become larger. Extracting it to a separate config file (e.g.,src/config/docs-navigation.ts) would improve maintainability and make it easier to update navigation structure.Example structure:
// src/config/docs-navigation.ts import { Home, FileText, Code, Book } from "lucide-react"; export const docsRoutes = [ // ... routes ];Then import in the component:
import { docsRoutes } from "@/config/docs-navigation";
104-107: Addaria-labelto menu button for better accessibility.The Sheet trigger button would benefit from an explicit
aria-labelto improve screen reader experience.Apply this diff:
<SheetTrigger asChild> - <Button variant="outline" size="icon"> + <Button variant="outline" size="icon" aria-label="Open navigation menu"> <Menu className="h-5 w-5" /> </Button> </SheetTrigger>
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (11)
mdx-components.tsx(1 hunks)next.config.js(1 hunks)package.json(2 hunks)src/app/docs/_components/sidebar.tsx(1 hunks)src/app/docs/components/page.md(1 hunks)src/app/docs/examples/page.md(1 hunks)src/app/docs/getting-started/page.md(1 hunks)src/app/docs/layout.tsx(1 hunks)src/app/docs/page.mdx(1 hunks)src/components/navbar/NavBar.server.tsx(1 hunks)src/styles/globals.css(1 hunks)
🧰 Additional context used
🧬 Code graph analysis (2)
src/app/docs/_components/sidebar.tsx (2)
src/lib/utils.ts (1)
cn(4-6)src/components/navbar/ThemeSwitch.client.tsx (1)
ThemeSwitch(8-39)
src/app/docs/layout.tsx (1)
src/app/docs/_components/sidebar.tsx (1)
DocsSidebar(87-117)
🪛 LanguageTool
src/app/docs/examples/page.md
[uncategorized] ~286-~286: Did you mean the formatting language “Markdown” (= proper noun)?
Context: ...--------| | MDX Support | Write docs in markdown | ✅ | | Syntax Highlighting | Beautiful...
(MARKDOWN_NNP)
🪛 markdownlint-cli2 (0.18.1)
src/app/docs/getting-started/page.md
27-27: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (14)
src/components/navbar/NavBar.server.tsx (1)
16-18: LGTM!The Docs navigation button follows the same pattern as the existing Home and Shadcn buttons and correctly links to the new
/docsroute.package.json (1)
26-28: LGTM!The MDX-related dependencies are appropriate for the documentation system. The versions are recent and align with the Next.js 15 and React 19 stack.
Also applies to: 79-80, 82-82
next.config.js (2)
6-6: LGTM!The MDX import and pageExtensions configuration correctly enable MDX support for
.mdand.mdxfiles.Also applies to: 9-11
13-32: The string-based plugin configuration is correct and documented.The original review comment incorrectly identifies string-based plugin names as non-standard. In @next/mdx (v15+) you can specify remark/rehype plugins by string names for Turbopack, and that approach is documented by Next.js for MDX + Turbopack.
The configuration in
next.config.jsfollows the documented pattern exactly:
remarkPlugins: ["remark-gfm"]— string without options ✓rehypePlugins: [["rehype-pretty-code", { theme: {...}, keepBackground: false }]]— string with serializable options ✓The build succeeded with no errors, confirming the configuration works correctly. No changes are needed.
Likely an incorrect or invalid review comment.
mdx-components.tsx (5)
1-8: LGTM!The imports are correctly structured, bringing in necessary types and components for MDX rendering.
12-33: LGTM!The heading and paragraph renderers provide appropriate styling with proper spacing and scroll margins for anchor navigation.
36-58: LGTM!The link renderer correctly handles external vs internal links with appropriate security attributes (
noopener noreferrer) and uses Next.jsLinkfor internal navigation.
72-114: LGTM!The code, blockquote, list, and table renderers are well-structured. The code renderer appropriately distinguishes between inline and block code using the
classNameprop, and tables are wrapped in a scrollable container for responsiveness.
116-129: LGTM!Exposing the Shadcn UI components in the MDX components map allows them to be used directly in MDX documentation, and the spread operator at the end allows for proper composition and overrides.
src/app/docs/getting-started/page.md (1)
1-26: LGTM!The getting started guide provides clear, accurate instructions for installation, development, and navigating the project. The technology stack listing is comprehensive and correct.
Also applies to: 38-60
src/app/docs/page.mdx (1)
1-31: LGTM!The documentation landing page is well-structured, providing a clear introduction to the documentation system with features, navigation guidance, and a code example.
src/app/docs/layout.tsx (1)
1-24: LGTM!The documentation layout is well-structured with appropriate metadata, a responsive two-column design, and proper prose styling for MDX content rendering.
src/styles/globals.css (1)
127-196: Excellent syntax highlighting and MDX prose integration.The implementation provides comprehensive support for:
- Dual theme support (media query + class-based) for consistent light/dark rendering
- Dynamic line number widths based on digit count
- Proper highlighted line styling
- Clean MDX prose overrides using Tailwind utilities
The styles integrate seamlessly with the existing theme system and follow established patterns.
src/app/docs/_components/sidebar.tsx (1)
87-117: Well-structured responsive navigation component.The implementation demonstrates solid patterns:
- Proper "use client" usage for interactive navigation
- Responsive design with desktop sticky sidebar and mobile Sheet menu
- Code reuse through shared
SidebarContentcomponent- Correct use of Next.js 15
usePathnamefor active state- Clean separation of concerns
The component integrates well with the documentation layout and provides good UX across devices.
| img: (props) => ( | ||
| <Image | ||
| {...(props as ImageProps)} | ||
| alt={props.alt ?? ""} | ||
| width={800} | ||
| height={600} | ||
| className="rounded-lg border" | ||
| /> | ||
| ), |
There was a problem hiding this comment.
Hardcoded dimensions will distort images.
The hardcoded width={800} and height={600} will distort any image that doesn't have a 4:3 aspect ratio. This affects visual quality in the documentation.
Consider one of these approaches:
Option 1 (recommended): Use responsive sizing without fixed dimensions
-img: (props) => (
- <Image
- {...(props as ImageProps)}
- alt={props.alt ?? ""}
- width={800}
- height={600}
- className="rounded-lg border"
- />
-),
+img: (props) => (
+ <Image
+ {...(props as ImageProps)}
+ alt={props.alt ?? ""}
+ width={props.width ?? 800}
+ height={props.height ?? 600}
+ className="rounded-lg border w-full h-auto"
+ />
+),Option 2: Use fill mode for responsive images
-img: (props) => (
- <Image
- {...(props as ImageProps)}
- alt={props.alt ?? ""}
- width={800}
- height={600}
- className="rounded-lg border"
- />
-),
+img: (props) => (
+ <div className="relative w-full aspect-video">
+ <Image
+ {...(props as ImageProps)}
+ alt={props.alt ?? ""}
+ fill
+ className="rounded-lg border object-contain"
+ />
+ </div>
+),📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| img: (props) => ( | |
| <Image | |
| {...(props as ImageProps)} | |
| alt={props.alt ?? ""} | |
| width={800} | |
| height={600} | |
| className="rounded-lg border" | |
| /> | |
| ), | |
| img: (props) => ( | |
| <Image | |
| {...(props as ImageProps)} | |
| alt={props.alt ?? ""} | |
| width={props.width ?? 800} | |
| height={props.height ?? 600} | |
| className="rounded-lg border w-full h-auto" | |
| /> | |
| ), |
🤖 Prompt for AI Agents
In mdx-components.tsx around lines 61–69, the Image component uses hardcoded
width={800} and height={600} which will distort images with different aspect
ratios; remove the fixed width/height and render the image responsively instead
— either (recommended) omit width/height and pass style={{ width: "100%",
height: "auto" }} (or set sizes and allow the loader to scale) so images keep
their intrinsic aspect ratio, or (alternative) use Next/Image fill mode by
wrapping the Image in a position:relative container with a fixed aspect or
responsive container and use fill plus objectFit: "contain"/"cover"; ensure
props are forwarded, alt fallback remains, and adjust className to preserve
rounded border styling.
| ### Basic Button | ||
|
|
||
| ```tsx | ||
| import { Button } from "~/components/ui/button"; |
There was a problem hiding this comment.
Incorrect import path alias in code examples.
The code examples use "~/components/ui/..." but the project uses "@/components/ui/..." (as seen in NavBar.server.tsx and other files). This inconsistency will cause the code examples to fail when users copy them.
Apply this fix to all import statements in the file:
-import { Button } from "~/components/ui/button";
+import { Button } from "@/components/ui/button";
-import { Card, CardHeader, CardTitle, CardDescription, CardContent } from "~/components/ui/card";
+import { Card, CardHeader, CardTitle, CardDescription, CardContent } from "@/components/ui/card";
-import { Alert, AlertTitle, AlertDescription } from "~/components/ui/alert";
+import { Alert, AlertTitle, AlertDescription } from "@/components/ui/alert";
-import { Button } from "~/components/ui/button";
-import { cn } from "~/lib/utils";
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";Also applies to: 64-64, 84-84, 137-137, 154-154
🤖 Prompt for AI Agents
In src/app/docs/components/page.md around lines 47, 64, 84, 137, and 154, the
code examples incorrectly import from "~/components/..." which doesn't match the
project's alias; replace all occurrences of the "~/components/..." import path
with the correct "@/components/..." path so the examples use the same alias as
the rest of the codebase (e.g., update import statements like import { Button }
from "~/components/ui/button" to import from "@/components/ui/button" across the
listed lines).
| ```tsx | ||
| "use client"; | ||
|
|
||
| import { api } from "~/trpc/react"; | ||
| import { Button } from "~/components/ui/button"; | ||
|
|
||
| export function ClientComponent() { | ||
| const [name, setName] = useState(""); | ||
| const utils = api.useUtils(); | ||
|
|
||
| const createPost = api.post.create.useMutation({ | ||
| onSuccess: async () => { | ||
| await utils.post.invalidate(); | ||
| }, | ||
| }); | ||
|
|
||
| return ( | ||
| <form | ||
| onSubmit={(e) => { | ||
| e.preventDefault(); | ||
| createPost.mutate({ name }); | ||
| }} | ||
| > | ||
| <input | ||
| value={name} | ||
| onChange={(e) => setName(e.target.value)} | ||
| placeholder="Title" | ||
| /> | ||
| <Button type="submit" disabled={createPost.isPending}> | ||
| {createPost.isPending ? "Submitting..." : "Submit"} | ||
| </Button> | ||
| </form> | ||
| ); | ||
| } |
There was a problem hiding this comment.
Missing useState import.
The example uses useState on line 60 but doesn't import it from React. This will cause a runtime error if users copy this code.
Apply this diff to add the missing import:
"use client";
+import { useState } from "react";
import { api } from "~/trpc/react";
import { Button } from "~/components/ui/button";🤖 Prompt for AI Agents
In src/app/docs/examples/page.md around lines 53 to 86, the component uses
useState (line ~60) but doesn't import it from React; add an import for useState
from 'react' at the top of the file (e.g., import { useState } from "react") so
the example compiles and runs correctly.
|
|
||
| Here's an example image loaded from the public folder: | ||
|
|
||
|  |
There was a problem hiding this comment.
🧩 Analysis chain
Verify image file exists in public folder.
Ensure the referenced image file exists at the expected path to prevent broken images in the documentation.
Run the following script to verify the image file exists:
🏁 Script executed:
#!/bin/bash
# Description: Check if the example image exists in the public folder
if [ -f "public/docs-images/example.png" ]; then
echo "✓ Image file exists"
else
echo "✗ Image file not found at public/docs-images/example.png"
exit 1
fiLength of output: 56
The referenced image file is missing.
The image at /docs-images/example.png does not exist in the public folder. Either add the image file to public/docs-images/example.png or update the reference in line 280 to point to an existing image.
🤖 Prompt for AI Agents
In src/app/docs/examples/page.md around line 280 the markdown references an
image at /docs-images/example.png which is missing; either add the image file to
public/docs-images/example.png (ensure correct filename and path) or update the
markdown reference on line 280 to point to an existing image path in the public
folder (or a valid external URL), then commit the added file or updated path so
the image renders.
| ``` | ||
| ├── src/ | ||
| │ ├── app/ # App router pages and layouts | ||
| │ ├── components/ # Reusable components | ||
| │ ├── lib/ # Utility functions | ||
| │ └── styles/ # Global styles | ||
| ├── docs/ # Documentation (this site!) | ||
| │ └── app/ # Docs pages | ||
| └── public/ # Static assets | ||
| ``` |
There was a problem hiding this comment.
Fix code block language and correct project structure.
Two minor documentation issues:
- The fenced code block is missing a language identifier (flagged by markdownlint MD040).
- The project structure shows
docs/at the root level, but the actual location issrc/app/docs/.
Apply this diff:
-```
+```text
├── src/
│ ├── app/ # App router pages and layouts
│ ├── components/ # Reusable components
│ ├── lib/ # Utility functions
│ └── styles/ # Global styles
-├── docs/ # Documentation (this site!)
-│ └── app/ # Docs pages
+│ └── app/
+│ └── docs/ # Documentation (this site!)
└── public/ # Static assets
-```
+````
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.18.1)</summary>
27-27: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
In src/app/docs/getting-started/page.md around lines 27 to 36, the fenced code
block lacks a language identifier and the shown project tree incorrectly places
docs/ at the repo root; replace the block with a fenced code block starting with
shown in the provided diff, then close the fence as in the diff.
This pull request introduces a full-featured documentation site for the project, built with Next.js 15 and MDX. It adds a new
/docsroute with a sidebar navigation, custom MDX component rendering, and several documentation pages covering getting started, components, and examples. The PR also updates dependencies to support MDX, syntax highlighting, and GitHub Flavored Markdown features.Documentation Site Implementation
/docsroute with a sidebar navigation (DocsSidebar) for desktop and mobile, integrating theme switching and navigation to main app sections. (src/app/docs/_components/sidebar.tsx)src/app/docs/layout.tsx).MDX and Markdown Rendering
mdx-components.tsx).src/app/docs/page.mdx), getting started guide (src/app/docs/getting-started/page.md), components overview (src/app/docs/components/page.md), and examples (src/app/docs/examples/page.md). [1] [2] [3] [4]Dependency Updates for Documentation
@mdx-js/loader,@mdx-js/react,@next/mdx,rehype-pretty-code,remark-gfm, andshikiinpackage.json. [1] [2]Navigation Integration
NavBar) for easy access to the documentation site. (src/components/navbar/NavBar.server.tsx)Summary by CodeRabbit