repository·main·Indexed 11 days ago
https://github.com/shuding/nextraA site generation framework powered by Next.js, optimized for creating documentation and blog sites with minimal configuration. It includes specialized themes like nextra-theme-docs and nextra-theme-blog, and supports advanced features such as MDX customization, LaTeX (via KaTeX and MathJax), Mermaid diagrams, and remote content rendering using MDXRemote.
The Nextra Docs Theme is a comprehensive theme for building modern documentation websites. It includes built-in support for:
nextra-theme-docs is a specialized theme designed for building documentation websites using Nextra. It provides the layout, navigation, and UI components necessary for a professional documentation experience.
You can see a live implementation of this theme at nextra.site.
nextra-theme-blog is a specialized theme for Nextra designed specifically for building blog websites. It provides the layout and components necessary to render blog posts within a Nextra-powered project.SWR provides several built-in features for managing data fetching and state:
Instead of multiple _meta files in different directories, you can define your entire site structure in a single _meta.global.js file.
Note: When using a global file, folder items must include an items field to define their children. You cannot use both _meta.global and local _meta files in the same project.
// _meta.global.js
export default {
fruits: {
type: 'page',
title: '✨ Fruits',
items: {
apple: '🍎 Apple',
banana: '🍌 BaNaNa'
}
}
}When using Turbopack, the nextra configuration function only supports JSON serializable values.
Because remarkPlugins, rehypePlugins, and recmaPlugins are functions, they cannot be passed in the mdxOptions when Turbopack is enabled. These plugin options are only supported when using the standard Webpack-based development mode or during next build (where Webpack is still used for builds).
If you attempt to pass non-serializable plugins while using Turbopack, you will encounter the following error:
Error: loader nextra/loader for match "./{src/app,app}/**/page.{md,mdx}" does not have serializable options. Ensure that options passed are plain JavaScript objects and values.
import nextra from 'nextra'
// This configuration will FAIL with Turbopack because plugins are functions
const withNextra = nextra({
mdxOptions: {
remarkPlugins: [myRemarkPlugin],
rehypePlugins: [myRehypePlugin],
recmaPlugins: [myRecmaPlugin]
}
})When using useSWR, you can distinguish between initial loading and background revalidation using isLoading and isValidating to improve User Experience (UX).
isValidating: Becomes true whenever there is an ongoing request, regardless of whether data has already been loaded.isLoading: Becomes true only when there is an ongoing request and data has not been loaded yet.UX Pattern:
Use isLoading to show a skeleton or full-page loader when no data is available. Use isValidating to show a subtle indicator (like a spinner) when data is already present but being refreshed in the background.
Note: Fallback data and data preserved via keepPreviousData are not considered "loaded data," so you may still have data to display even if isLoading is true.
function Stock() {
const { data, isLoading, isValidating } = useSWR(STOCK_API, fetcher, {
refreshInterval: 3000
})
// If it's still loading the initial data, there is nothing to display.
// We return a skeleton here.
if (isLoading) return <div className="skeleton" />
// Otherwise, display the data and a spinner that indicates a background
// revalidation.
return (
<>
<div>${data}</div>
{isValidating ? <div className="spinner" /> : null}
</>
)
}When <SWRConfig> components are nested, you can extend the existing cache provider. The provider function receives the upper-level cache provider as its first argument, allowing you to wrap or augment it.
<SWRConfig value={{ provider: cache => newCache }}>...</SWRConfig>In Nextra, the page.mdx file follows the Next.js App Router convention to define the UI unique to a specific route. While Next.js natively supports .js, .jsx, or .tsx extensions for pages, Nextra extends this capability by allowing you to use .md and .mdx extensions. This enables you to write your route content using Markdown or MDX directly within your App Router structure.
app/
docs/
page.mdx <-- Defines the UI for /docs
getting-started/
page.mdx <-- Defines the UI for /docs/getting-started