Project structure

Gridlines separates content from presentation. Writers mostly work in MDX files, while designers and developers customize the shared components and theme.

Top-level folders#

This tree shows where routes, reusable components, and content live in the project.

src/
  app/
    docs/
      [[...slug]]/
        page.tsx
    blog/
      [slug]/
        page.tsx
  components/
    docs-sidebar.tsx
    docs-toc.tsx
    mdx-components.tsx
    navigation.tsx
  content/
    docs/
    blog/

Content#

Docs pages live in src/content/docs. Blog posts live in src/content/blog. These folders are the main surface area for writers.

Components#

The docs sidebar, table of contents, navigation, and MDX component map are normal React components. Customize them like the rest of your app.

Blog asset structure#

Each blog post should have its own folder so the article and cover image stay together.

src/content/blog/
  writing-release-notes-users-read/
    index.mdx
    cover.jpg

Why colocate assets#

Colocation makes posts easier to move, delete, and review. A folder should contain the article and the assets required to render it.

Route structure#

Routes define how content becomes pages. Keep route files small and let shared components handle repeated layout details.

Docs route#

The docs route should load the current page, render its MDX body, and pass navigation data to sidebar and table of contents components.

Blog route#

The blog route should focus on article metadata, cover images, and a readable article layout. It should not duplicate the docs sidebar behavior.

Component structure#

Shared components are the right place for reusable UI decisions. Put repeated prose styling, image handling, code tabs, and install commands behind stable component APIs.

Local ownership#

Keep docs-specific components near the docs experience and general UI primitives in the shared UI folder. This makes future changes easier to locate.