[v3] add auto-import-theme-style option in nextra configuration (#3220)

* [v3] add auto-import-theme-style option in nextra configuration

* remove the style field in `package.json`

* Update .changeset/red-rockets-perform.md

Co-authored-by: Dimitri POSTOLOV <dmytropostolov@gmail.com>

* dry in styles.css swr-site example

---------

Co-authored-by: Dimitri POSTOLOV <dmytropostolov@gmail.com>

.changeset/red-rockets-perform.md

@@ -0,0 +1,6 @@
+---
+'nextra-theme-docs': patch
+'nextra': patch
+---
+
+Add the `autoImportThemeStyle` option to the Nextra configuration. This allows users to import the official Nextra theme CSS into a specific cascade layer.

.gitignore

@@ -13,3 +13,4 @@ out/
 
 tsup.config.bundled*
 tsconfig.tsbuildinfo
+pagefind/

examples/swr-site/next.config.js

@@ -32,7 +32,8 @@ export function getStaticProps() {
     }
     return pageMap
   },
-  latex: true
+  latex: true,
+  autoImportThemeStyle: false
 })
 
 const withBundleAnalyzer = bundleAnalyzer({

examples/swr-site/package.json

@@ -36,6 +36,7 @@
     "@next/bundle-analyzer": "^13.4.19",
     "autoprefixer": "^10.4.16",
     "postcss": "^8.4.33",
+    "postcss-import": "^16.0.0",
     "tailwindcss": "^3.4.1"
   },
   "nextBundleAnalysis": {

examples/swr-site/postcss.config.cjs

@@ -1,6 +1,7 @@
 /** @type {import('postcss').Postcss} */
 module.exports = {
   plugins: {
+    'postcss-import': {},
     tailwindcss: {},
     autoprefixer: {}
   }

examples/swr-site/styles.css

@@ -1,27 +1,22 @@
+@import 'nextra-theme-docs/dist/style.css' layer(nextra-base);
+
 @tailwind utilities;
 
 .dark .invert-on-dark {
   filter: invert(1) brightness(1.8);
 }
 
 body {
-  background:
-    linear-gradient(
-      to bottom,
-      rgba(255, 255, 255, 0) 0%,
-      rgb(var(--nextra-bg)) 300px
-    ),
-    fixed 0 0 / 20px 20px radial-gradient(#d1d1d1 1px, transparent 0),
-    fixed 10px 10px / 20px 20px radial-gradient(#d1d1d1 1px, transparent 0);
-}
+  --bg-dot-color: #d1d1d1;
+
+  .dark & {
+    --bg-dot-color: #313131;
+  }
 
-.dark body {
   background:
-    linear-gradient(
-      to bottom,
-      rgba(0, 0, 0, 0) 0%,
-      rgb(var(--nextra-bg)) 300px
-    ),
-    fixed 0 0 / 20px 20px radial-gradient(#313131 1px, transparent 0),
-    fixed 10px 10px / 20px 20px radial-gradient(#313131 1px, transparent 0);
+    linear-gradient(to bottom, transparent, rgb(var(--nextra-bg)) 300px),
+    fixed 0 0 / 20px 20px
+      radial-gradient(var(--bg-dot-color) 1px, transparent 0),
+    fixed 10px 10px / 20px 20px
+      radial-gradient(var(--bg-dot-color) 1px, transparent 0);
 }

packages/nextra/src/server/constants.ts

@@ -27,7 +27,8 @@ export const DEFAULT_CONFIG = {
   search: {
     codeblocks: true
   },
-  codeHighlight: true
+  codeHighlight: true,
+  autoImportThemeStyle: true
 } satisfies Partial<NextraConfig>
 
 export const OFFICIAL_THEMES = ['nextra-theme-docs', 'nextra-theme-blog']

packages/nextra/src/server/loader.ts

@@ -64,7 +64,8 @@ export async function loader(
     codeHighlight,
     transform,
     mdxOptions,
-    locales
+    locales,
+    autoImportThemeStyle
   } = this.getOptions()
 
   const mdxPath = this._module?.resourceResolveData
@@ -106,7 +107,7 @@ export const getStaticProps = () => ({ notFound: true })`
 
   const cssImports = `
 ${latex ? "import 'katex/dist/katex.min.css'" : ''}
-${OFFICIAL_THEMES.includes(theme) ? `import '${theme}/style.css'` : ''}`
+${OFFICIAL_THEMES.includes(theme) && autoImportThemeStyle ? `import '${theme}/style.css'` : ''}`
 
   if (currentPath.includes('/pages/_app.')) {
     isAppFileFromNodeModules = currentPath.includes('/node_modules/')

packages/nextra/src/server/schemas.ts

@@ -106,7 +106,8 @@ export const nextraConfigSchema = z
       recmaPlugins: z.custom<ProcessorOptions['recmaPlugins']>(),
       format: z.enum(['detect', 'mdx', 'md']),
       rehypePrettyCodeOptions: z.custom<RehypePrettyCodeOptions>()
-    })
+    }),
+    autoImportThemeStyle: z.boolean()
   })
   // eslint-disable-next-line deprecation/deprecation -- fixme
   .deepPartial()