[v3] improve toc for remote content (#2375)

Author: Dimitri POSTOLOV

.changeset/slow-countries-sell.md

@@ -0,0 +1,6 @@
+---
+'nextra-theme-docs': major
+'nextra': major
+---
+
+use toc with JSX elements for remote content

docs/pages/about.mdx

@@ -26,7 +26,6 @@ Nextra is powered by these incredible open source projects:
 - https://pnpm.io
 - https://tailwindcss.com
 - https://github.com/pacocoursey/next-themes
-- https://github.com/hashicorp/next-mdx-remote
 - https://github.com/antfu/shikiji
 - https://github.com/nextapps-de/flexsearch
 - https://github.com/atomiks/rehype-pretty-code

packages/nextra-theme-blog/__test__/__fixture__/pageMap.ts

@@ -1,6 +1,7 @@
-import type { BlogPageOpts } from '../../src'
+import type { PageOpts } from 'nextra'
+import type { NextraBlogTheme } from '../../src'
 
-export const indexOpts: BlogPageOpts = {
+export const indexOpts: PageOpts = {
   filePath: 'index.mdx',
   frontMatter: {
     type: 'page',
@@ -61,7 +62,7 @@ export const indexOpts: BlogPageOpts = {
   title: 'Nextra'
 }
 
-export const postsOpts: BlogPageOpts = {
+export const postsOpts: PageOpts = {
   filePath: 'index.md',
   frontMatter: {
     type: 'posts',
@@ -120,7 +121,7 @@ export const postsOpts: BlogPageOpts = {
   title: 'Random Thoughts'
 }
 
-export const articleOpts: BlogPageOpts = {
+export const articleOpts: PageOpts = {
   filePath: 'aaron-swartz-a-programmable-web.mdx',
   frontMatter: {
     title: 'Notes on A Programmable Web by Aaron Swartz',
@@ -182,7 +183,7 @@ export const articleOpts: BlogPageOpts = {
   title: 'Notes on A Programmable Web by Aaron Swartz'
 }
 
-export const config = {
+export const config: NextraBlogTheme = {
   readMore: 'Read More →',
   darkMode: true
 }

packages/nextra-theme-blog/src/article-layout.tsx

@@ -0,0 +1,14 @@
+import { createContext, useContext } from 'react'
+import type { LayoutProps } from './types'
+
+const BlogContext = createContext<LayoutProps | null>(null)
+
+export const BlogProvider = BlogContext.Provider
+
+export const useBlogContext = () => {
+  const value = useContext(BlogContext)
+  if (!value) {
+    throw new Error('useBlogContext must be used within a BlogProvider')
+  }
+  return value
+}

packages/nextra-theme-blog/src/basic-layout.tsx

@@ -1,50 +1,85 @@
 import { ThemeProvider } from 'next-themes'
+import Head from 'next/head'
 import type { NextraThemeLayoutProps } from 'nextra'
-import type { ReactElement, ReactNode } from 'react'
-import { ArticleLayout } from './article-layout'
+import { MDXProvider } from 'nextra/mdx'
+import { useRef } from 'react'
 import { BlogProvider } from './blog-context'
 import { DEFAULT_THEME } from './constants'
-import { PageLayout } from './page-layout'
+import { components, HeadingContext } from './mdx-theme'
+import Meta from './meta'
+import Nav from './nav'
 import { PostsLayout } from './posts-layout'
-import type { LayoutProps } from './types'
+import type { BlogFrontMatter } from './types'
+import { isValidDate } from './utils/date'
 
-const layoutMap = {
-  post: ArticleLayout,
-  page: PageLayout,
-  posts: PostsLayout,
-  tag: PostsLayout
-}
+const layoutSet = new Set(['post', 'page', 'posts', 'tag'])
 
-const BlogLayout = ({
-  config,
+export default function NextraLayout({
   children,
-  opts
-}: LayoutProps & { children: ReactNode }): ReactElement => {
-  const type = opts.frontMatter.type || 'post'
-  const Layout = layoutMap[type]
-  if (!Layout) {
+  pageOpts,
+  themeConfig
+}: NextraThemeLayoutProps<BlogFrontMatter>) {
+  const config = { ...DEFAULT_THEME, ...themeConfig }
+
+  const ref = useRef<HTMLHeadingElement>(null)
+
+  const { title: pageTitle, frontMatter } = pageOpts
+
+  frontMatter.type ||= 'post'
+
+  const { type, date } = frontMatter
+  if (!layoutSet.has(type)) {
     throw new Error(
       `nextra-theme-blog does not support the layout type "${type}" It only supports "post", "page", "posts" and "tag"`
     )
   }
-  return (
-    <BlogProvider opts={opts} config={config}>
-      <Layout>{children}</Layout>
-    </BlogProvider>
-  )
-}
 
-export default function Layout({
-  children,
-  ...context
-}: NextraThemeLayoutProps) {
-  const extendedConfig = { ...DEFAULT_THEME, ...context.themeConfig }
+  if (date && !isValidDate(date)) {
+    throw new Error(
+      `Invalid date "${date}". Provide date in "YYYY/M/D", "YYYY/M/D H:m", "YYYY-MM-DD", "[YYYY-MM-DD]T[HH:mm]" or "[YYYY-MM-DD]T[HH:mm:ss.SSS]Z" format.`
+    )
+  }
+
+  const title = `${pageTitle}${config.titleSuffix || ''}`
+
+  const Footer = {
+    post: () => (
+      <>
+        {config.postFooter}
+        {config.comments}
+      </>
+    ),
+    posts: PostsLayout,
+    tag: PostsLayout,
+    page: null
+  }[type]
 
   return (
     <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
-      <BlogLayout config={extendedConfig} opts={context.pageOpts}>
-        {children}
-      </BlogLayout>
+      <Head>
+        <title>{title}</title>
+        {config.head?.({ title, meta: frontMatter })}
+      </Head>
+      <BlogProvider value={{ config, opts: pageOpts }}>
+        <article
+          className="_container _prose max-md:_prose-sm dark:_prose-dark"
+          dir="ltr"
+        >
+          <HeadingContext.Provider value={ref}>
+            {pageOpts.hasJsxInH1 ? <h1 ref={ref} /> : null}
+            {pageOpts.hasJsxInH1 ? null : <h1>{pageTitle}</h1>}
+            {type === 'post' ? <Meta /> : <Nav />}
+
+            <MDXProvider components={{ ...components, ...config.components }}>
+              {children}
+            </MDXProvider>
+
+            {Footer && <Footer />}
+          </HeadingContext.Provider>
+
+          {config.footer}
+        </article>
+      </BlogProvider>
     </ThemeProvider>
   )
 }

packages/nextra-theme-blog/src/blog-context.ts

@@ -1,6 +1,5 @@
 import Link from 'next/link'
 import { Code, Pre, Table, Td, Th, Tr } from 'nextra/components'
-import { MDXProvider } from 'nextra/mdx'
 import type { Components } from 'nextra/mdx'
 import type { ComponentProps, ReactElement, ReactNode, RefObject } from 'react'
 import {
@@ -76,34 +75,22 @@ const A = ({ children, href = '', ...props }: ComponentProps<'a'>) => {
   )
 }
 
-const useComponents = (): Components => {
-  const { config } = useBlogContext()
-  return {
-    h1: H1,
-    h2: props => <HeadingLink tag="h2" {...props} />,
-    h3: props => <HeadingLink tag="h3" {...props} />,
-    h4: props => <HeadingLink tag="h4" {...props} />,
-    h5: props => <HeadingLink tag="h5" {...props} />,
-    h6: props => <HeadingLink tag="h6" {...props} />,
-    a: A,
-    pre: ({ children, ...props }) => (
-      <div className="_not-prose">
-        <Pre {...props}>{children}</Pre>
-      </div>
-    ),
-    tr: Tr,
-    th: Th,
-    td: Td,
-    table: props => <Table className="_not-prose" {...props} />,
-    code: Code,
-    ...config.components
-  }
-}
-
-export const MDXTheme = ({
-  children
-}: {
-  children: ReactNode
-}): ReactElement => {
-  return <MDXProvider components={useComponents()}>{children}</MDXProvider>
+export const components: Components = {
+  h1: H1,
+  h2: props => <HeadingLink tag="h2" {...props} />,
+  h3: props => <HeadingLink tag="h3" {...props} />,
+  h4: props => <HeadingLink tag="h4" {...props} />,
+  h5: props => <HeadingLink tag="h5" {...props} />,
+  h6: props => <HeadingLink tag="h6" {...props} />,
+  a: A,
+  pre: ({ children, ...props }) => (
+    <div className="_not-prose">
+      <Pre {...props}>{children}</Pre>
+    </div>
+  ),
+  tr: Tr,
+  th: Th,
+  td: Td,
+  table: props => <Table className="_not-prose" {...props} />,
+  code: Code
 }

packages/nextra-theme-blog/src/blog-context.tsx

@@ -1,18 +1,11 @@
 import Link from 'next/link'
 import { useRouter } from 'next/router'
-import type { ReactElement, ReactNode } from 'react'
-import { BasicLayout } from './basic-layout'
+import type { ReactElement } from 'react'
 import { useBlogContext } from './blog-context'
-import { MDXTheme } from './mdx-theme'
-import Nav from './nav'
 import { collectPostsAndNavs } from './utils/collect'
 import getTags from './utils/get-tags'
 
-export function PostsLayout({
-  children
-}: {
-  children: ReactNode
-}): ReactElement {
+export function PostsLayout(): ReactElement {
   const { config, opts } = useBlogContext()
   const { posts } = collectPostsAndNavs({ config, opts })
   const router = useRouter()
@@ -63,11 +56,5 @@ export function PostsLayout({
       </div>
     )
   })
-  return (
-    <BasicLayout>
-      <Nav />
-      <MDXTheme>{children}</MDXTheme>
-      {postList}
-    </BasicLayout>
-  )
+  return <>{postList}</>
 }

packages/nextra-theme-blog/src/index.tsx

@@ -25,8 +25,6 @@ export interface NextraBlogTheme {
   titleSuffix?: string
 }
 
-export type BlogPageOpts = PageOpts<BlogFrontMatter>
-
 export type BlogFrontMatter = {
   author?: string
   back?: string
@@ -39,5 +37,5 @@ export type BlogFrontMatter = {
 
 export interface LayoutProps {
   config: NextraBlogTheme
-  opts: BlogPageOpts
+  opts: PageOpts<BlogFrontMatter>
 }