DocsPluginsShowcaseReleases
npmStar us on GitHub

Getting Started

IntroductionInstallationProject StructureLayouts and PagesLinking and Navigating

Routing

Folder-Based RoutingFile-Based RoutingDynamic RoutesParallel RoutesIntercepting RoutesCatch-All RoutesMDX & Markdown Pages

Special Files

Loading UIError BoundariesTemplateDefaultNot Found

Data Fetching

LoadersActionsAccessing Route Data

Metadata

Metadata & SEOOpen Graph & TwitterIcons & Favicons

API Routes

API Routes OverviewPlain Function HandlersHono IntegrationDynamic API Routes

Environment Variables

OverviewPrefixes & Client ExposureUsing in API Routes

Styling

CSS OverviewTailwind CSSCSS Modules

Platforms

WebWindowsmacOSLinuxAndroidiOS

Deployment

Deployment OverviewProduction ServerStatic ExportHosting Providers

A native React framework for building cross-platform applications from a single codebase.

Resources

  • Documentation
  • Plugins
  • Showcase
  • Releases

Community

  • GitHub Discussions
  • Reddit
  • Discord
  • LinkedIn

More

  • npm
  • GitHub
  • Issues
  • License

© 2026 Bini Cooperation.

MDX and Markdown

MDX and Markdown content routes with JSX support, compiled through @mdx-js/rollup.

What is MDX?

MDX extends Markdown with JSX, so you can use components directly in a content file. Bini.js supports .mdx and .md as page routes. Both compile through the same MDX pipeline, with full JSX, import, and export support.

File typeDescription
.mdxMarkdown with JSX components
.mdMarkdown, compiled through the same MDX pipeline (no plain-only mode)

The MDX compiler is included with every Bini.js project, so there is nothing to install. Add an .mdx or .md file and it compiles automatically as part of the build.

MDX Pages

Add an .mdx file anywhere in src/app/. The file compiles to a React component and creates a URL based on its location, exactly like a page.tsx file.

app
about.mdx
blog
page.mdx
[slug].mdx
contact.mdx
/about
/blog
/blog/:slug
/contact
src/app/about.mdx
# About Us

Welcome to our company. This is a regular **Markdown** page with JSX support.

<Button variant="primary">Get Started</Button>

## Our Mission

We build amazing products with Bini.js.

Markdown Pages

Plain .md files go through the same MDX pipeline. They support JSX and imports, just like .mdx. There is no plain-markdown-only mode.

app
docs
getting-started.md
privacy.md
terms.md
/docs/getting-started
/privacy
/terms
src/app/terms.md
# Terms of Service

## 1. Acceptance of Terms

By using our service, you agree to these terms.

## 2. User Responsibilities

Users are responsible for their content and activity.

---

*Last updated: January 2024*

Imports in MDX

Import components, utilities, and hooks directly in MDX. Auto-imports do not apply to .mdx or .md files, so import React hooks and React Router APIs explicitly.

src/app/interactive.mdx
import { useState } from 'react'
import { Link } from 'react-router-dom'
import { Button } from '@/components/Button'

# Interactive Page

<Button variant="primary">Click Me</Button>
Auto-imports (useState, Link, getEnv, and the rest) apply to script files only. In .mdx and .md, import what you need.

Styling MDX Content

CSS Modules, plain CSS imports, and Tailwind utility classes work in MDX files exactly as they do in a page.tsx file.

src/app/about.mdx
import styles from './About.module.css'
import { Button } from '@/components/Button'

# About Us

<div className={styles.container}>
  <p className="text-slate-600 dark:text-slate-300">
    This uses Tailwind classes and CSS Modules.
  </p>
  <Button>Learn More</Button>
</div>
Tailwind's Preflight reset removes default heading and bold styling. Wrap plain Markdown in a prose class from @tailwindcss/typography to restore typographic defaults.

Limitations

MDX and Markdown are for content pages. Structural files and static exports are not supported in them.

FeatureSupported in .mdx / .md?
Page routesYes
Flat content routesYes
layout, template, loading, error, not-found, global-error, defaultNo - must use .tsx / .jsx / .ts / .js
metadata exportNo - script files only
document exportNo - script files only
CSS extractionNo - script files only
A layout in a parent folder still contributes metadata to its MDX children. If a single MDX route needs its own title or description, put a layout.tsx in the same folder and export metadata from the layout, not from the MDX file.

MDX vs Markdown

.mdx and .md are identical in behavior, because both go through the same MDX compiler. Use .mdx when a file contains JSX components, and .md when it is plain Markdown. Both support JSX, so the choice is purely about file extension.

Behavior.mdx.md
Creates a page routeYesYes
JSX componentsYesYes
Imports and exportsYesYes
Auto-importsNoNo
metadata exportNoNo

Complete Example

A project mixing MDX, Markdown, and script-based routes.

app
layout.tsx
page.tsx
about.mdx
blog
layout.tsx
page.mdx
[slug].mdx
docs
[[...slug]]
page.md
contact.mdx
/
/about
/blog
/blog/:slug
/docs/*
/contact
File pathURL
src/app/page.tsx/
src/app/about.mdx/about
src/app/blog/page.mdx/blog
src/app/blog/[slug].mdx/blog/:slug
src/app/docs/[[...slug]]/page.md/docs/*
The root layout.tsx exports the site-wide metadata. The blog layout.tsx exports metadata for every post, including the MDX pages under it. Neither .mdx nor .md exports metadata itself.

Catch-All Routes

Match any number of trailing URL segments.

Metadata & SEO

Control titles, descriptions, and social previews per route.

Layouts and Pages

Create your first pages and wrap them in shared layouts.

Folder-Based Routing

Define routes with folders and page files inside them.

File-Based Routing

Define routes with flat files instead of folders.

Static Export

How every route is pre-rendered to HTML at build time.

Was this helpful?
PreviousCatch-All Routes
NextLoading UI

On this page

  • What is MDX?
  • MDX Pages
  • Markdown Pages
  • Imports in MDX
  • Styling MDX Content
  • Limitations
  • MDX vs Markdown
  • Complete Example
Edit this page on GitHub

MDX and Markdown

MDX and Markdown content routes with JSX support, compiled through @mdx-js/rollup.

What is MDX?

MDX extends Markdown with JSX, so you can use components directly in a content file. Bini.js supports .mdx and .md as page routes. Both compile through the same MDX pipeline, with full JSX, import, and export support.

File typeDescription
.mdxMarkdown with JSX components
.mdMarkdown, compiled through the same MDX pipeline (no plain-only mode)

The MDX compiler is included with every Bini.js project, so there is nothing to install. Add an .mdx or .md file and it compiles automatically as part of the build.

MDX Pages

Add an .mdx file anywhere in src/app/. The file compiles to a React component and creates a URL based on its location, exactly like a page.tsx file.

app
about.mdx
blog
page.mdx
[slug].mdx
contact.mdx
/about
/blog
/blog/:slug
/contact
src/app/about.mdx
# About Us

Welcome to our company. This is a regular **Markdown** page with JSX support.

<Button variant="primary">Get Started</Button>

## Our Mission

We build amazing products with Bini.js.

Markdown Pages

Plain .md files go through the same MDX pipeline. They support JSX and imports, just like .mdx. There is no plain-markdown-only mode.

app
docs
getting-started.md
privacy.md
terms.md
/docs/getting-started
/privacy
/terms
src/app/terms.md
# Terms of Service

## 1. Acceptance of Terms

By using our service, you agree to these terms.

## 2. User Responsibilities

Users are responsible for their content and activity.

---

*Last updated: January 2024*

Imports in MDX

Import components, utilities, and hooks directly in MDX. Auto-imports do not apply to .mdx or .md files, so import React hooks and React Router APIs explicitly.

src/app/interactive.mdx
import { useState } from 'react'
import { Link } from 'react-router-dom'
import { Button } from '@/components/Button'

# Interactive Page

<Button variant="primary">Click Me</Button>
Auto-imports (useState, Link, getEnv, and the rest) apply to script files only. In .mdx and .md, import what you need.

Styling MDX Content

CSS Modules, plain CSS imports, and Tailwind utility classes work in MDX files exactly as they do in a page.tsx file.

src/app/about.mdx
import styles from './About.module.css'
import { Button } from '@/components/Button'

# About Us

<div className={styles.container}>
  <p className="text-slate-600 dark:text-slate-300">
    This uses Tailwind classes and CSS Modules.
  </p>
  <Button>Learn More</Button>
</div>
Tailwind's Preflight reset removes default heading and bold styling. Wrap plain Markdown in a prose class from @tailwindcss/typography to restore typographic defaults.

Limitations

MDX and Markdown are for content pages. Structural files and static exports are not supported in them.

FeatureSupported in .mdx / .md?
Page routesYes
Flat content routesYes
layout, template, loading, error, not-found, global-error, defaultNo - must use .tsx / .jsx / .ts / .js
metadata exportNo - script files only
document exportNo - script files only
CSS extractionNo - script files only
A layout in a parent folder still contributes metadata to its MDX children. If a single MDX route needs its own title or description, put a layout.tsx in the same folder and export metadata from the layout, not from the MDX file.

MDX vs Markdown

.mdx and .md are identical in behavior, because both go through the same MDX compiler. Use .mdx when a file contains JSX components, and .md when it is plain Markdown. Both support JSX, so the choice is purely about file extension.

Behavior.mdx.md
Creates a page routeYesYes
JSX componentsYesYes
Imports and exportsYesYes
Auto-importsNoNo
metadata exportNoNo

Complete Example

A project mixing MDX, Markdown, and script-based routes.

app
layout.tsx
page.tsx
about.mdx
blog
layout.tsx
page.mdx
[slug].mdx
docs
[[...slug]]
page.md
contact.mdx
/
/about
/blog
/blog/:slug
/docs/*
/contact
File pathURL
src/app/page.tsx/
src/app/about.mdx/about
src/app/blog/page.mdx/blog
src/app/blog/[slug].mdx/blog/:slug
src/app/docs/[[...slug]]/page.md/docs/*
The root layout.tsx exports the site-wide metadata. The blog layout.tsx exports metadata for every post, including the MDX pages under it. Neither .mdx nor .md exports metadata itself.

Catch-All Routes

Match any number of trailing URL segments.

Metadata & SEO

Control titles, descriptions, and social previews per route.

Layouts and Pages

Create your first pages and wrap them in shared layouts.

Folder-Based Routing

Define routes with folders and page files inside them.

File-Based Routing

Define routes with flat files instead of folders.

Static Export

How every route is pre-rendered to HTML at build time.

Was this helpful?
PreviousCatch-All Routes
NextLoading UI

On this page

  • What is MDX?
  • MDX Pages
  • Markdown Pages
  • Imports in MDX
  • Styling MDX Content
  • Limitations
  • MDX vs Markdown
  • Complete Example
Edit this page on GitHub