Taxonomy

Taxonomy is an experimental open-source application designed to demonstrate the capabilities of Next.js 13+ features like the App Router and Server Components. It serves as a reference for building modern applications with the following stack:

• Framework: Next.js (App Router, Server/Client Components, Route Handlers, Middleware)
• Authentication: NextAuth.js
• Database & ORM: Prisma with PlanetScale
• Styling: Tailwind CSS
• UI Components: Radix UI
• Content/Docs: MDX and Contentlayer
• Payments/Subscriptions: Stripe
• Validation: Zod
• Language: TypeScript

Taxonomy provides a foundation for building documentation sites by combining MDX for content authoring with Contentlayer for content transformation and validation.

Key features included in this setup:

• Content Authoring: Write content using MDX.
• Content Pipeline: Use Contentlayer to transform and validate MDX files.
• MDX Components: Use pre-built components like <Callout /> and <Card /> directly within your markdown.
• Navigation: Built-in support for Table of Contents and custom navigation (previous/next page).
• Code Rendering: High-quality code blocks powered by rehype-pretty-code and shiki for syntax highlighting.

⚠️ This project has been officially archived and will no longer receive updates.

Because this project was started during the Next.js App Router public preview, it may contain:

• Deprecated APIs or patterns.
• Code that does not reflect current best practices.
• Implementation details not recommended for production environments.

For modern Next.js starters, refer to the Vercel Templates directory.

When using Tailwind CSS, default browser styling is removed from elements like h1, p, and ul. To style content coming from a headless CMS, a rich-text editor, or a Markdown file without manually adding utility classes to every element, use the @tailwindcss/typography plugin.

By applying the prose class to a container element, all vanilla HTML content inside that container will receive beautiful, well-formatted typographic styles automatically.

<article class="prose">
  <h1>Garlic bread with cheese: What the science tells us</h1>
  <p>
    For years parents have espoused the health benefits of eating garlic bread
    with cheese to their children...
  </p>
</article>

You can customize the rendering of standard HTML elements (like <hr />, <h1>, etc.) by adding them to the components object passed to the MDX renderer. This allows you to apply global styles or custom React components to standard Markdown syntax.

const components = {
  Callout,
  CustomComponent,
  hr: ({ ...props }) => <hr className="my-4 border-slate-200 md:my-6" />,
}

To use your own React components within MDX files, you must pass them to the components prop of the component returned by useMDXComponent.

1. Define a mapping object containing your components.
2. Pass this object to the <Component /> instance inside your MDX renderer.

import { Callout } from "@/components/callout"
import { CustomComponent } from "@/components/custom"

const components = {
  Callout,
  CustomComponent,
}

export function Mdx({ code }) {
  const Component = useMDXComponent(code)

  return (
    <div className="mdx">
      <Component components={components} />
    </div>
  )
}

The Card component is used to wrap content in a styled container, typically used for headings and descriptions. It accepts an href prop to make the entire card a link.

You can use standard HTML/Tailwind classes (like grid) to arrange multiple cards in a layout.

<Card href="#">

#### Heading

You can use **markdown** inside cards.

</Card>

To support GitHub Flavored Markdown (GFM) features in your Markdown processing pipeline, use the remark-gfm plugin. This enables features such as:

• Autolink literals: Automatically converts URLs (e.g., www.example.com or https://example.com) and email addresses (e.g., contact@example.com) into clickable <a> tags.

The Callout component allows you to display highlighted information blocks within your Markdown files. You can control the visual style using the type prop.

Supported type values:

• default (default behavior)
• warning
• danger

You can embed standard Markdown syntax inside the component tags.

<Callout type="warning">
This is a warning callout. It uses the props `type="warning"`.
</Callout>

You can apply Tailwind CSS classes directly to elements within MDX files using the className prop.

Important: To ensure Tailwind picks up these styles, you must include the directory containing your .md and .mdx files in the content array of your tailwind.config.js file.

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./app/**/*.{ts,tsx}",
    "./components/**/*.{ts,tsx}",
    "./content/**/*.{md,mdx}",
  ],
}