shuding · dimaMachina · Nov 12, 2024 · Nov 10, 2024 · Nov 10, 2024 · Nov 10, 2024
diff --git a/.changeset/chilled-turkeys-smell.md b/.changeset/chilled-turkeys-smell.md
@@ -0,0 +1,7 @@
+---
+'nextra-theme-blog': major
+'nextra-theme-docs': major
+'nextra': major
+---
+
+make `compileMdx` from `nextra/compile` return a `string` instead of an `object`
diff --git a/docs/app/docs/advanced/customize-the-cascade-layers/page.mdx b/docs/app/docs/advanced/customize-the-cascade-layers/page.mdx
@@ -1,3 +1,7 @@
+---
+sidebarTitle: Customize Cascade Layers
+---
+
 import { Steps } from 'nextra/components'
 
 # Customize the Cascade Layers
@@ -46,12 +50,8 @@ Import your CSS file at the top-level layout of your application (e.g.
 ```jsx filename="app/layout.jsx"
 import '../path/to/your/styles.css'
 
-export default function RootLayout({ children }) {
-  return (
-    <html lang="en">
-      <body>{children}</body>
-    </html>
-  )
+export default async function RootLayout({ children }) {
+  // ... Your layout logic here
 }
 ```
 

diff --git a/docs/app/docs/advanced/latex/page.mdx b/docs/app/docs/advanced/latex/page.mdx
@@ -1,3 +1,7 @@
+---
+icon: FormulaIcon
+---
+
 import { compileMdx } from 'nextra/compile'
 import { MDXRemote } from 'nextra/mdx-remote'
 import {
@@ -185,7 +189,7 @@ export async function MathJaxExample() {
 \\int_2^3x^3\\,\\mathrm{d}x
 ~~~
 `
-  const { result } = await compileMdx(
+  const rawJs = await compileMdx(
     rawMdx,
     {
       latex: {
@@ -203,5 +207,5 @@ export async function MathJaxExample() {
     }
   )
 
-  return <MDXRemote compiledSource={result} components={{ MathJax, MathJaxContext }} />
+  return <MDXRemote compiledSource={rawJs} components={{ MathJax, MathJaxContext }} />
 }
diff --git a/docs/app/docs/advanced/mermaid/page.mdx b/docs/app/docs/advanced/mermaid/page.mdx
@@ -1,3 +1,7 @@
+---
+icon: DiagramIcon
+---
+
 import { compileMdx } from 'nextra/compile'
 import { Mermaid } from 'nextra/components'
 import { MDXRemote } from 'nextra/mdx-remote'
@@ -35,13 +39,13 @@ Z --> E;
 Z --> F;
 Z --> G;
 \`\`\``
-  const { result } = await compileMdx(`${mermaidCodeblock}
+  const rawJs = await compileMdx(`${mermaidCodeblock}
 
 ## Usage
 
 ~~~md filename="Markdown"
 ${mermaidCodeblock}
 ~~~
 `)
-  return <MDXRemote compiledSource={result} components={{ Mermaid }} />
+  return <MDXRemote compiledSource={rawJs} components={{ Mermaid }} />
 }
diff --git a/docs/app/docs/advanced/npm2yarn/page.mdx b/docs/app/docs/advanced/npm2yarn/page.mdx
@@ -1,3 +1,7 @@
+---
+icon: TerminalIcon
+---
+
 import { compileMdx } from 'nextra/compile'
 import { Tabs } from 'nextra/components'
 import { MDXRemote } from 'nextra/mdx-remote'
@@ -21,11 +25,11 @@ export async function Page() {
   const codeBlock = `\`\`\`sh npm2yarn
 npm i -D @graphql-eslint/eslint-plugin
 \`\`\``
-  const { result } = await compileMdx(`${codeBlock}
+  const rawJs = await compileMdx(`${codeBlock}
 ## Usage
 
 ~~~md filename="Markdown" /npm2yarn/
 ${codeBlock}
 ~~~`)
-  return <MDXRemote compiledSource={result} components={{ $Tabs: Tabs }} />
+  return <MDXRemote compiledSource={rawJs} components={{ $Tabs: Tabs }} />
 }
diff --git a/docs/app/docs/advanced/page.mdx b/docs/app/docs/advanced/page.mdx
@@ -11,49 +11,21 @@ import {
 } from '@components/icons'
 import { Cards } from 'nextra/components'
 import { TerminalIcon, TypeScriptIcon } from 'nextra/icons'
+import { MDXRemote } from 'nextra/mdx-remote'
+import { createIndexPage, getPageMap } from 'nextra/page-map'
 
 # Advanced
 
-<Cards>
-  <Cards.Card
-    icon={<TerminalIcon />}
-    title="Npm2Yarn"
-    href="/docs/advanced/npm2yarn"
-  />
-  <Cards.Card
-    icon={<DiagramIcon />}
-    title="Mermaid"
-    href="/docs/advanced/mermaid"
-  />
-  <Cards.Card
-    icon={<TailwindIcon />}
-    title="Tailwind CSS"
-    href="/docs/advanced/tailwind-css"
-  />
-  <Cards.Card
-    icon={<FormulaIcon />}
-    title="LaTeX"
-    href="/docs/advanced/latex"
-  />
-  <Cards.Card
-    icon={<TableIcon />}
-    title="Rendering Tables"
-    href="/docs/advanced/table"
-  />
-  <Cards.Card
-    icon={<TypeScriptIcon />}
-    title="TypeScript"
-    href="/docs/advanced/typescript"
-  />
-  <Cards.Card
-    icon={<CloudIcon />}
-    title="Remote Content"
-    href="/docs/advanced/remote"
-  />
-  <Cards.Card title="Playground" href="/docs/advanced/playground" />
-  <Cards.Card
-    title="Customize Cascade Layers"
-    href="/docs/advanced/customize-the-cascade-layers"
-  />
-  <Cards.Card title="Twoslash Support" href="/docs/advanced/twoslash-support" />
-</Cards>
+<MDXRemote
+  compiledSource={await createIndexPage(await getPageMap('', '/docs/advanced'))}
+  components={{
+    Cards,
+    TerminalIcon,
+    DiagramIcon,
+    TailwindIcon,
+    FormulaIcon,
+    TableIcon,
+    TypeScriptIcon,
+    CloudIcon
+  }}
+/>
diff --git a/docs/app/docs/advanced/remote/page.mdx b/docs/app/docs/advanced/remote/page.mdx
@@ -1,3 +1,7 @@
+---
+icon: CloudIcon
+---
+
 # Remote Content
 
 import { Callout } from 'nextra/components'

diff --git a/docs/app/docs/advanced/table/page.mdx b/docs/app/docs/advanced/table/page.mdx
@@ -1,3 +1,7 @@
+---
+icon: TableIcon
+---
+
 import { Callout, Table } from 'nextra/components'
 
 # Rendering Tables

diff --git a/docs/app/docs/advanced/tailwind-css/page.mdx b/docs/app/docs/advanced/tailwind-css/page.mdx
@@ -1,19 +1,29 @@
+---
+icon: TailwindIcon
+---
+
+import { Steps } from 'nextra/components'
+
 # Tailwind CSS
 
 Tailwind CSS is a CSS framework that provides a set of pre-defined CSS classes
 to quickly style elements. You can follow the official
 [Tailwind CSS documentation for Next.js](https://tailwindcss.com/docs/guides/nextjs)
 to set up Tailwind CSS for your Nextra project.
 
+<Steps>
+
+## Create `tailwind.config.js` file
+
 To use Tailwind classes in your Markdown files, you will also need to add `.md`
 and `.mdx` files to the `content` list in `tailwind.config.js`:
 
 ```js filename="tailwind.config.js" /md,mdx/
 /** @type {import('tailwindcss').Config} */
-module.exports = {
+export default {
   content: [
-    './pages/**/*.{js,jsx,ts,tsx,md,mdx}',
-    './components/**/*.{js,jsx,ts,tsx,md,mdx}',
+    './app/**/*.{js,jsx,ts,tsx,md,mdx}',
+    './content/**/*.{md,mdx}',
 
     // Or if using `src` directory:
     './src/**/*.{js,jsx,ts,tsx,md,mdx}'
@@ -25,20 +35,38 @@ module.exports = {
 }
 ```
 
-Next step, create a CSS file for Tailwind directives, `globals.css` for example:
+> [!TIP]
+>
+> You can also use a `tailwind.config.ts` file if you prefer TypeScript for your
+> Tailwind CSS configuration.
+
+## Create the `globals.css` file
+
+Create a CSS file for Tailwind directives, `globals.css` for example:
 
 ```css filename="globals.css"
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+@tailwind base; /* Apply Tailwind's base styles (Preflight) */
+@tailwind components; /* Include component styles */
+@tailwind utilities; /* Include utility classes */
 ```
 
-Then import into `pages/_app.jsx`
+> [!NOTE]
+>
+> If you're using `nextra-theme-docs` or `nextra-theme-blog`, you don't need to
+> include the `@tailwind base` directive. These themes already import Tailwind's
+> preflight styles in their `style.css` files.
+
+## Import styles in the Root Layout
 
-```jsx filename="_app.jsx"
+To apply the styles globally, import the `globals.css` file in your root layout
+file:
+
+```jsx filename="app/layout.jsx"
 import '../path/to/your/globals.css'
 
-export default function App({ Component, pageProps }) {
-  return <Component {...pageProps} />
+export default async function RootLayout({ children }) {
+  // ... Your layout logic here
 }
 ```
+
+</Steps>
diff --git a/docs/app/docs/advanced/typescript/page.mdx b/docs/app/docs/advanced/typescript/page.mdx
@@ -1,3 +1,7 @@
+---
+icon: TypeScriptIcon
+---
+
 import { Steps } from 'nextra/components'
 
 # TypeScript

diff --git a/docs/app/docs/blog-theme/page.mdx b/docs/app/docs/blog-theme/page.mdx
@@ -5,13 +5,17 @@ sidebarTitle: Blog Theme
 
 import { ChevronRightIcon } from '@components/icons'
 import { Cards } from 'nextra/components'
+import { MDXRemote } from 'nextra/mdx-remote'
+import { createIndexPage, getPageMap } from 'nextra/page-map'
 
 # Nextra Blog Theme
 
-<Cards>
-  <Cards.Card
-    icon={<ChevronRightIcon />}
-    title="Get Started"
-    href="/docs/blog-theme/start"
-  />
-</Cards>
+<MDXRemote
+  compiledSource={await createIndexPage(
+    await getPageMap('', '/docs/blog-theme')
+  )}
+  components={{
+    Cards,
+    ChevronRightIcon
+  }}
+/>
diff --git a/docs/app/docs/blog-theme/start/page.mdx b/docs/app/docs/blog-theme/start/page.mdx
@@ -1,3 +1,7 @@
+---
+icon: ChevronRightIcon
+---
+
 import InstallNextraTheme from '@components/install-nextra-theme.mdx'
 import ReadeToGo from '@components/ready-to-go.mdx'
 import { Steps } from 'nextra/components'
@@ -32,28 +36,6 @@ npm i next react react-dom nextra nextra-theme-blog
 
 <InstallNextraTheme />
 
-### Add Next.js Config
-
-Create the following `next.config.mjs` file in your project's root directory:
-
-```js filename="next.config.mjs"
-import nextra from 'nextra'
-
-const withNextra = nextra({
-  theme: 'nextra-theme-blog',
-  themeConfig: './theme.config.jsx'
-})
-
-export default withNextra()
-
-// If you have other Next.js configurations, you can pass them as the parameter:
-// export default withNextra({ /* other next.js config */ })
-```
-
-With the above configuration, Nextra can handle Markdown files in your Next.js
-project, with the specified theme. Other Nextra configurations can be found in
-[Guide](/docs/guide).
-
 ### Create Blog Theme Config
 
 Lastly, create the corresponding `theme.config.jsx` file in your project's root

diff --git a/docs/app/docs/built-ins/cards/page.mdx b/docs/app/docs/built-ins/cards/page.mdx
@@ -38,7 +38,7 @@ export async function CardsPage() {
     href="/docs/guide/built-ins/steps"
   />
 </Cards>`
-  const { result } = await compileMdx(`
+  const rawJs = await compileMdx(`
 ## Grouped Cards
 
 ### Example
@@ -76,7 +76,7 @@ ${mdx2}
 ~~~mdx filename="MDX"
 ${mdx2}
 ~~~`)
-  return <MDXRemote compiledSource={result} components={{ Cards, CardsIcon, OneIcon, WarningIcon, BoxIcon }}  />
+  return <MDXRemote compiledSource={rawJs} components={{ Cards, CardsIcon, OneIcon, WarningIcon, BoxIcon }}  />
 }
 
 <CardsPage />
diff --git a/docs/app/docs/built-ins/filetree/page.mdx b/docs/app/docs/built-ins/filetree/page.mdx
@@ -14,7 +14,7 @@ A built-in component to visually represent a file tree.
 Click the folder to test the dynamic functionality of the file tree.
 
 <FileTree>
-  <FileTree.Folder name="pages" defaultOpen>
+  <FileTree.Folder name="content" defaultOpen>
     <FileTree.File name="_meta.js" />
     <FileTree.File name="contact.md" />
     <FileTree.File name="index.mdx" />
@@ -36,7 +36,7 @@ with the `name` attribute. Use `defaultOpen` to set the folder to open on load.
 import { FileTree } from 'nextra/components'
 
 <FileTree>
-  <FileTree.Folder name="pages" defaultOpen>
+  <FileTree.Folder name="content" defaultOpen>
     <FileTree.File name="_meta.js" />
     <FileTree.File name="contact.md" />
     <FileTree.File name="index.mdx" />