Skip to content

Docusaurus 3.8 #4607

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 22 commits into from
May 27, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions website/docusaurus.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ import path from 'path';
import users from './showcase.json';
import versions from './versions.json';

// See https://docs.netlify.com/configure-builds/environment-variables/
const isProductionDeployment =
!!process.env.NETLIFY && process.env.CONTEXT === 'production';

const lastVersion = versions[0];
const copyright = `Copyright © ${new Date().getFullYear()} Meta Platforms, Inc.`;

Expand Down Expand Up @@ -63,6 +67,8 @@ const isDeployPreview = process.env.PREVIEW_DEPLOY === 'true';

const config: Config = {
future: {
// Turns Docusaurus v4 future flags on to make it easier to upgrade later
v4: true,
// Make Docusaurus build faster - enabled by default
// See https://github.com/facebook/docusaurus/issues/10556
// See https://github.com/facebook/react-native-website/pull/4268
Expand Down Expand Up @@ -154,6 +160,21 @@ const config: Config = {
],
plugins: [
'docusaurus-plugin-sass',
function disableExpensiveBundlerOptimizationPlugin() {
return {
name: 'disable-expensive-bundler-optimizations',
configureWebpack(_config, isServer) {
// This optimization is expensive and only reduces by 3% the JS assets size
// Let's skip it for local and deploy preview builds
// See also https://github.com/facebook/docusaurus/discussions/11199
return {
optimization: {
concatenateModules: isProductionDeployment ? !isServer : false,
},
};
},
};
},
Comment on lines +163 to +177
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Optional but this can significantly reduce build time for local production builds and deploy previews.

See also facebook/docusaurus#11199

See benchmarks with/without this optimization in the PR description.

[
'content-docs',
{
Expand Down
16 changes: 8 additions & 8 deletions website/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -51,21 +51,21 @@
]
},
"dependencies": {
"@docusaurus/core": "3.6.3",
"@docusaurus/faster": "3.6.3",
"@docusaurus/plugin-google-gtag": "3.6.3",
"@docusaurus/plugin-pwa": "3.6.3",
"@docusaurus/preset-classic": "3.6.3",
"@docusaurus/core": "3.8.0",
"@docusaurus/faster": "3.8.0",
"@docusaurus/plugin-google-gtag": "3.8.0",
"@docusaurus/plugin-pwa": "3.8.0",
"@docusaurus/preset-classic": "3.8.0",
"docusaurus-plugin-sass": "^0.2.5",
"react": "^18.2.0",
"react-dom": "^18.2.0",
"react-github-btn": "^1.4.0",
"sass": "1.76.0"
},
"devDependencies": {
"@docusaurus/module-type-aliases": "3.6.3",
"@docusaurus/tsconfig": "3.6.3",
"@docusaurus/types": "3.6.3",
"@docusaurus/module-type-aliases": "3.8.0",
"@docusaurus/tsconfig": "3.8.0",
"@docusaurus/types": "3.8.0",
"@react-native-website/lint-examples": "0.0.0",
"@react-native-website/update-redirects": "0.0.0",
"@types/google.analytics": "^0.0.46",
Expand Down
40 changes: 31 additions & 9 deletions website/src/css/customTheme.scss
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,6 @@
--ifm-table-border-color: var(--ifm-toc-border-color);
--ifm-table-cell-padding: 10px;
--ifm-table-stripe-background: rgba(0, 0, 0, 0.02);
--docusaurus-blog-social-icon-size: 16px;
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was not used, and after introducing cascade layers, it became used and produced a visual diff that my tool caught.

The effective icon size on the RN website in prod is 17px, not 16px.


@media (min-width: 340px) {
--ifm-navbar-sidebar-width: 340px;
Expand Down Expand Up @@ -223,8 +222,14 @@ html[data-theme="dark"] {
}
}

main[class^="docMainContainer"] > .container {
padding-top: 2rem !important;
/*
Layer needed to override utility rules using !important in the Infima layer
See also https://css-tricks.com/css-cascade-layers/#aa-important-layers
*/
@layer docusaurus.infima.importantOverrides {
main[class^="docMainContainer"] > .container {
padding-top: 2rem !important;
}
}
Comment on lines +225 to 233
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Our Infima utility types such as margin--xl use !important

Once layered, these rules can't be overridden by unlayered CSS, and you have to add your override directly to the Infima layer with !important to be able to override it.

All this is explained here: https://css-tricks.com/css-cascade-layers/#aa-important-layers.

This may seem annoying, but I think it makes sense. Utility classes serve to drive the styling from the markup. If you write margin--xl in the HTML, it's a bit weird if the final margin is not "xl" but another value due to an unexpected override. You can see this as a way to be explicit and say "hey, I know what I'm doing, and really want to override even if this is dangerous and can lead to unexpected behavior.

The proper way would be to swizzle the component and remove margin--xl for example, but I understand how it might feel more practical to just use CSS 🤪

PS: the name "importantOverrides doesn't matter much, what matters is that it's a "sub-layer" of Infima.


div[class^="generatedIndexPage"] {
Expand Down Expand Up @@ -268,6 +273,10 @@ hr {
}

blockquote {
> :last-child {
margin-bottom: 0;
}
Comment on lines +276 to +278
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your site's custom CSS now overrides what comes from Infima and Docusaurus.

This broke our CSS rule that prevents an useless extra margin at the end of blockquote by default.

CleanShot 2025-05-26 at 18 29 55

I'm moving this rule here so that you can keep the same behavior:


background-color: var(--rn-note-background);
border-left: 8px solid var(--ifm-color-warning);
padding: 15px 30px 15px 15px;
Expand Down Expand Up @@ -568,8 +577,10 @@ html[data-theme="dark"] .alert--secondary {
text-decoration-thickness: 1px !important;
}

.margin-top--md {
margin-top: 0.33rem !important;
@layer docusaurus.infima.importantOverrides {
.margin-top--md {
margin-top: 0.33rem !important;
}
}
}

Expand Down Expand Up @@ -1854,6 +1865,10 @@ html[data-theme="dark"] .docsRating {
border-radius: var(--ifm-global-radius);
}

.tabs-container .snack-player:last-child {
margin-bottom: 0;
}

/* Two columns code block */

.two-columns {
Expand Down Expand Up @@ -1888,10 +1903,15 @@ html[data-theme="dark"] .docsRating {
color: var(--ifm-font-color-secondary);
}

@layer docusaurus.infima.importantOverrides {
.container.margin-vert--lg {
margin-top: 0 !important;
margin-bottom: 0 !important;
}
}

.container.margin-vert--lg {
max-width: calc(100% - (var(--ifm-spacing-horizontal)) * 4);
margin-top: 0 !important;
margin-bottom: 0 !important;

.col.text--right a {
@extend %button-link-style;
Expand Down Expand Up @@ -1934,8 +1954,10 @@ html[data-theme="dark"] .docsRating {
}
}

article.margin-bottom--xl {
margin-bottom: 2.5rem !important;
@layer docusaurus.infima.importantOverrides {
article.margin-bottom--xl {
margin-bottom: 2.5rem !important;
}
}

aside nav {
Expand Down
Loading