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.

Sign up for GitHub

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
+677 −1,012
Merged

Docusaurus 3.8 #4607

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
dede178
Docusaurus 3.7
slorber May 14, 2025
f6ee389
Docusaurus 3.8 + React 19.1
slorber May 14, 2025
a761cf1
Upgrade canary + revert examples
szymonrybczak Apr 29, 2025
a3e2d75
yarn dedupe
slorber May 23, 2025
da91238
Add Infima important override
slorber May 23, 2025
01d3d03
fix colorModeToggle_ selector
slorber May 23, 2025
f813793
remove
slorber May 23, 2025
94cd833
Merge branch 'main' into slorber/docusaurus-3.7
slorber May 23, 2025
4219522
apply infima override
slorber May 23, 2025
0200da9
Merge remote-tracking branch 'origin/slorber/docusaurus-3.7' into slo…
slorber May 23, 2025
5773cce
apply infima override
slorber May 23, 2025
0d4477d
remove unused CSS var
slorber May 23, 2025
33a6489
add importantOverrides
slorber May 23, 2025
858ccc6
Merge branch 'main' into slorber/docusaurus-3.7
slorber May 23, 2025
0a614b4
restore snack player last item margin from theme
slorber May 23, 2025
e3d4313
Merge remote-tracking branch 'origin/slorber/docusaurus-3.7' into slo…
slorber May 23, 2025
d56b594
restore infima quote margin bottom rule
slorber May 23, 2025
b1b7e48
add disableExpensiveBundlerOptimizationPlugin
slorber May 26, 2025
52fda41
ref
slorber May 26, 2025
f778c03
Merge branch 'main' into slorber/docusaurus-3.7
slorber May 26, 2025
2567cdb
Upgrade to Docusaurus 3.8 stable
slorber May 27, 2025
af4fe5f
Merge remote-tracking branch 'origin/slorber/docusaurus-3.7' into slo…
slorber May 27, 2025
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
View file
Open in desktop
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
View file
Open in desktop
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
View file
Open in desktop
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