From 2d35edf91123d9d6f6cbaab5c29b223c7ed58e1d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=A9bastien=20Lorber?= Date: Wed, 31 May 2023 16:22:25 +0200 Subject: [PATCH] feat(theme): add ability to inject data attributes from query-string - possibility to create an iframe/embed variant of a page (#9028) --- .../docusaurus-theme-classic/src/index.ts | 27 +++++++++++++---- website/docs/styling-layout.mdx | 30 +++++++++++++++++-- website/src/css/custom.css | 8 +++++ 3 files changed, 57 insertions(+), 8 deletions(-) diff --git a/packages/docusaurus-theme-classic/src/index.ts b/packages/docusaurus-theme-classic/src/index.ts index 68b4cf4e82bc..48a80606ac10 100644 --- a/packages/docusaurus-theme-classic/src/index.ts +++ b/packages/docusaurus-theme-classic/src/index.ts @@ -26,7 +26,10 @@ const ContextReplacementPlugin = requireFromDocusaurusCore( // Need to be inlined to prevent dark mode FOUC // Make sure the key is the same as the one in `/theme/hooks/useTheme.js` const ThemeStorageKey = 'theme'; +// Support for ?docusaurus-theme=dark const ThemeQueryStringKey = 'docusaurus-theme'; +// Support for ?docusaurus-data-mode=embed&docusaurus-data-myAttr=42 +const DataQueryStringPrefixKey = 'docusaurus-data-'; const noFlashColorMode = ({ defaultMode, @@ -42,19 +45,15 @@ const noFlashColorMode = ({ } function getQueryStringTheme() { - var theme = null; try { - theme = new URLSearchParams(window.location.search).get('${ThemeQueryStringKey}') + return new URLSearchParams(window.location.search).get('${ThemeQueryStringKey}') } catch(e) {} - return theme; } function getStoredTheme() { - var theme = null; try { - theme = localStorage.getItem('${ThemeStorageKey}'); + return localStorage.getItem('${ThemeStorageKey}'); } catch (err) {} - return theme; } var initialTheme = getQueryStringTheme() || getStoredTheme(); @@ -77,6 +76,21 @@ const noFlashColorMode = ({ } })();`; +/* language=js */ +const DataAttributeQueryStringInlineJavaScript = ` +(function() { + try { + const entries = new URLSearchParams(window.location.search).entries(); + for (var [searchKey, value] of entries) { + if (searchKey.startsWith('${DataQueryStringPrefixKey}')) { + var key = searchKey.replace('${DataQueryStringPrefixKey}',"data-") + document.documentElement.setAttribute(key, value); + } + } + } catch(e) {} +})(); +`; + // Duplicated constant. Unfortunately we can't import it from theme-common, as // we need to support older nodejs versions without ESM support // TODO: import from theme-common once we only support Node.js with ESM support @@ -205,6 +219,7 @@ export default function themeClassic( tagName: 'script', innerHTML: ` ${noFlashColorMode(colorMode)} +${DataAttributeQueryStringInlineJavaScript} ${announcementBar ? AnnouncementBarInlineJavaScript : ''} `, }, diff --git a/website/docs/styling-layout.mdx b/website/docs/styling-layout.mdx index cac5c8ca8600..af653e814174 100644 --- a/website/docs/styling-layout.mdx +++ b/website/docs/styling-layout.mdx @@ -3,6 +3,7 @@ description: A Docusaurus site is a pre-rendered single-page React application. --- import ColorGenerator from '@site/src/components/ColorGenerator'; +import IframeWindow from '@site/src/components/BrowserWindow/IframeWindow'; # Styling and Layout @@ -133,8 +134,33 @@ It is possible to initialize the Docusaurus theme directly from a `docusaurus-th Examples: -- [`https://docusaurus.io/?docusaurus-theme=dark`](https://docusaurus.io/?docusaurus-theme=dark) -- [`https://docusaurus.io/docs/configuration?docusaurus-theme=light`](https://docusaurus.io/docs/configuration?docusaurus-theme=light) + + + + +::: + +### Data Attributes {#data-attributes} + +It is possible to inject `` data attributes with query string parameters following the `docusaurus-data-` pattern. This gives you the flexibility to style a page differently based on the query string. + +For example, let's render one of our pages with a red border and no navbar: + +```css title="/src/css/custom.css" +html[data-navbar='false'] .navbar { + display: none; +} + +html[data-red-border] div#__docusaurus { + border: red solid thick; +} +``` + + + +:::tip Iframe Mode + +If you plan to embed some Docusaurus pages on another site though an iframe, it can be useful to create an alternative display mode and use iframe urls such as `https://mysite.com/docs/myDoc?docusaurus-data-mode=iframe`. It is your responsibility to provide the additional styles and decide which UI elements you want to keep or hide. ::: diff --git a/website/src/css/custom.css b/website/src/css/custom.css index 11125c5cadf8..ee42cd91be91 100644 --- a/website/src/css/custom.css +++ b/website/src/css/custom.css @@ -230,3 +230,11 @@ div[class^='announcementBar_'] { [data-theme='dark'] [data-rmiz-modal-overlay='visible'] { background-color: rgba(0 0 0 / 95%); } + +html[data-navbar='false'] .navbar { + display: none; +} + +html[data-red-border] div#__docusaurus { + border: red solid thick; +}