@docusaurus/theme-classic 3.3.2 → 3.4.0

package/lib/index.d.ts

@@ -7,7 +7,6 @@
 /// <reference path="../src/theme-classic.d.ts" />
 import type { LoadContext, Plugin } from '@docusaurus/types';
 import type { PluginOptions } from '@docusaurus/theme-classic';
-export declare const AnnouncementBarDismissStorageKey = "docusaurus.announcement.dismiss";
 export default function themeClassic(context: LoadContext, options: PluginOptions): Plugin<undefined>;
 export { default as getSwizzleConfig } from './getSwizzleConfig';
 export { validateThemeConfig, validateOptions } from './options';

package/lib/index.js

@@ -6,102 +6,21 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateOptions = exports.validateThemeConfig = exports.getSwizzleConfig = exports.AnnouncementBarDismissStorageKey = void 0;
+exports.validateOptions = exports.validateThemeConfig = exports.getSwizzleConfig = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
 const module_1 = require("module");
 const rtlcss_1 = tslib_1.__importDefault(require("rtlcss"));
 const theme_translations_1 = require("@docusaurus/theme-translations");
 const translations_1 = require("./translations");
+const inlineScripts_1 = require("./inlineScripts");
 const requireFromDocusaurusCore = (0, module_1.createRequire)(require.resolve('@docusaurus/core/package.json'));
 const ContextReplacementPlugin = requireFromDocusaurusCore('webpack/lib/ContextReplacementPlugin');
-// 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, respectPrefersColorScheme, }) => 
-/* language=js */
-`(function() {
-  var defaultMode = '${defaultMode}';
-  var respectPrefersColorScheme = ${respectPrefersColorScheme};
-
-  function setDataThemeAttribute(theme) {
-    document.documentElement.setAttribute('data-theme', theme);
-  }
-
-  function getQueryStringTheme() {
-    try {
-      return new URLSearchParams(window.location.search).get('${ThemeQueryStringKey}')
-    } catch(e) {}
-  }
-
-  function getStoredTheme() {
-    try {
-      return localStorage.getItem('${ThemeStorageKey}');
-    } catch (err) {}
-  }
-
-  var initialTheme = getQueryStringTheme() || getStoredTheme();
-  if (initialTheme !== null) {
-    setDataThemeAttribute(initialTheme);
-  } else {
-    if (
-      respectPrefersColorScheme &&
-      window.matchMedia('(prefers-color-scheme: dark)').matches
-    ) {
-      setDataThemeAttribute('dark');
-    } else if (
-      respectPrefersColorScheme &&
-      window.matchMedia('(prefers-color-scheme: light)').matches
-    ) {
-      setDataThemeAttribute('light');
-    } else {
-      setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
-    }
-  }
-})();`;
-/* 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
-// + move all those announcementBar stuff there too
-exports.AnnouncementBarDismissStorageKey = 'docusaurus.announcement.dismiss';
-const AnnouncementBarDismissDataAttribute = 'data-announcement-bar-initially-dismissed';
-// We always render the announcement bar html on the server, to prevent layout
-// shifts on React hydration. The theme can use CSS + the data attribute to hide
-// the announcement bar asap (before React hydration)
-/* language=js */
-const AnnouncementBarInlineJavaScript = `
-(function() {
-  function isDismissed() {
-    try {
-      return localStorage.getItem('${exports.AnnouncementBarDismissStorageKey}') === 'true';
-    } catch (err) {}
-    return false;
-  }
-  document.documentElement.setAttribute('${AnnouncementBarDismissDataAttribute}', isDismissed());
-})();`;
 function getInfimaCSSFile(direction) {
     return `infima/dist/css/default/default${direction === 'rtl' ? '-rtl' : ''}.css`;
 }
 function themeClassic(context, options) {
-    const { i18n: { currentLocale, localeConfigs }, } = context;
+    const { i18n: { currentLocale, localeConfigs }, siteStorage, } = context;
     const themeConfig = context.siteConfig.themeConfig;
     const { announcementBar, colorMode, prism: { additionalLanguages }, } = themeConfig;
     const { customCss } = options;
@@ -171,9 +90,9 @@ function themeClassic(context, options) {
                     {
                         tagName: 'script',
                         innerHTML: `
-${noFlashColorMode(colorMode)}
-${DataAttributeQueryStringInlineJavaScript}
-${announcementBar ? AnnouncementBarInlineJavaScript : ''}
+${(0, inlineScripts_1.getThemeInlineScript)({ colorMode, siteStorage })}
+${inlineScripts_1.DataAttributeQueryStringInlineJavaScript}
+${announcementBar ? (0, inlineScripts_1.getAnnouncementBarInlineScript)({ siteStorage }) : ''}
             `,
                     },
                 ],

package/lib/inlineScripts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import type { SiteStorage } from '@docusaurus/types';
+import type { ThemeConfig } from '@docusaurus/theme-common';
+export declare function getThemeInlineScript({ colorMode: { defaultMode, respectPrefersColorScheme }, siteStorage, }: {
+    colorMode: ThemeConfig['colorMode'];
+    siteStorage: SiteStorage;
+}): string;
+export declare const DataAttributeQueryStringInlineJavaScript = "\n(function() {\n  try {\n    const entries = new URLSearchParams(window.location.search).entries();\n    for (var [searchKey, value] of entries) {\n      if (searchKey.startsWith('docusaurus-data-')) {\n        var key = searchKey.replace('docusaurus-data-',\"data-\")\n        document.documentElement.setAttribute(key, value);\n      }\n    }\n  } catch(e) {}\n})();\n";
+export declare function getAnnouncementBarInlineScript({ siteStorage, }: {
+    siteStorage: SiteStorage;
+}): string;

package/lib/inlineScripts.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getAnnouncementBarInlineScript = exports.DataAttributeQueryStringInlineJavaScript = exports.getThemeInlineScript = void 0;
+// Support for ?docusaurus-theme=dark
+const ThemeQueryStringKey = 'docusaurus-theme';
+// Support for ?docusaurus-data-mode=embed&docusaurus-data-myAttr=42
+const DataQueryStringPrefixKey = 'docusaurus-data-';
+function getThemeInlineScript({ colorMode: { defaultMode, respectPrefersColorScheme }, siteStorage, }) {
+    // Need to be inlined to prevent dark mode FOUC
+    // Make sure the key is the same as the one in the color mode React context
+    // Currently defined in: `docusaurus-theme-common/src/contexts/colorMode.tsx`
+    const themeStorageKey = `theme${siteStorage.namespace}`;
+    /* language=js */
+    return `(function() {
+    var defaultMode = '${defaultMode}';
+    var respectPrefersColorScheme = ${respectPrefersColorScheme};
+
+    function setDataThemeAttribute(theme) {
+      document.documentElement.setAttribute('data-theme', theme);
+    }
+
+    function getQueryStringTheme() {
+      try {
+        return new URLSearchParams(window.location.search).get('${ThemeQueryStringKey}')
+      } catch (e) {
+      }
+    }
+
+    function getStoredTheme() {
+      try {
+        return window['${siteStorage.type}'].getItem('${themeStorageKey}');
+      } catch (err) {
+      }
+    }
+
+    var initialTheme = getQueryStringTheme() || getStoredTheme();
+    if (initialTheme !== null) {
+      setDataThemeAttribute(initialTheme);
+    } else {
+      if (
+        respectPrefersColorScheme &&
+        window.matchMedia('(prefers-color-scheme: dark)').matches
+      ) {
+        setDataThemeAttribute('dark');
+      } else if (
+        respectPrefersColorScheme &&
+        window.matchMedia('(prefers-color-scheme: light)').matches
+      ) {
+        setDataThemeAttribute('light');
+      } else {
+        setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
+      }
+    }
+  })();`;
+}
+exports.getThemeInlineScript = getThemeInlineScript;
+/* language=js */
+exports.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) {}
+})();
+`;
+// We always render the announcement bar html on the server, to prevent layout
+// shifts on React hydration. The theme can use CSS + the data attribute to hide
+// the announcement bar asap (before React hydration)
+function getAnnouncementBarInlineScript({ siteStorage, }) {
+    // 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 support Node.js with ESM support
+    // + move all those announcementBar stuff there too
+    const AnnouncementBarDismissStorageKey = `docusaurus.announcement.dismiss${siteStorage.namespace}`;
+    const AnnouncementBarDismissDataAttribute = 'data-announcement-bar-initially-dismissed';
+    /* language=js */
+    return `(function() {
+  function isDismissed() {
+    try {
+      return localStorage.getItem('${AnnouncementBarDismissStorageKey}') === 'true';
+    } catch (err) {}
+    return false;
+  }
+  document.documentElement.setAttribute('${AnnouncementBarDismissDataAttribute}', isDismissed());
+})();`;
+}
+exports.getAnnouncementBarInlineScript = getAnnouncementBarInlineScript;

package/lib/theme/BlogTagsPostsPage/index.js

@@ -52,7 +52,7 @@ function BlogTagsPostsPageMetadata({tag}) {
   const title = useBlogTagsPostsPageTitle(tag);
   return (
     <>
-      <PageMetadata title={title} />
+      <PageMetadata title={title} description={tag.description} />
       <SearchMetadata tag="blog_tags_posts" />
     </>
   );
@@ -64,6 +64,7 @@ function BlogTagsPostsPageContent({tag, items, sidebar, listMetadata}) {
       {tag.unlisted && <Unlisted />}
       <header className="margin-bottom--xl">
         <Heading as="h1">{title}</Heading>
+        {tag.description && <p>{tag.description}</p>}
         <Link href={tag.allTagsPath}>
           <Translate
             id="theme.tags.tagsPageLink"

package/lib/theme/DocCard/index.js

@@ -23,7 +23,7 @@ function useCategoryItemsPlural() {
       count,
       translate(
         {
-          message: '{count} items',
+          message: '1 item|{count} items',
           id: 'theme.docs.DocCard.categoryDescription.plurals',
           description:
             'The default description for a category card in the generated index about how many items this category includes',

package/lib/theme/DocTagDocListPage/index.js

@@ -55,10 +55,10 @@ function DocItem({doc}) {
     </article>
   );
 }
-function DocTagDocListPageMetadata({title}) {
+function DocTagDocListPageMetadata({title, tag}) {
   return (
     <>
-      <PageMetadata title={title} />
+      <PageMetadata title={title} description={tag.description} />
       <SearchMetadata tag="doc_tag_doc_list" />
     </>
   );
@@ -73,6 +73,7 @@ function DocTagDocListPageContent({tag, title}) {
             {tag.unlisted && <Unlisted />}
             <header className="margin-bottom--xl">
               <Heading as="h1">{title}</Heading>
+              {tag.description && <p>{tag.description}</p>}
               <Link href={tag.allTagsPath}>
                 <Translate
                   id="theme.tags.tagsPageLink"

package/lib/theme/Tag/index.d.ts

@@ -7,4 +7,4 @@
 /// <reference path="../../../src/theme-classic.d.ts" />
 /// <reference types="react" />
 import type { Props } from '@theme/Tag';
-export default function Tag({ permalink, label, count }: Props): JSX.Element;
+export default function Tag({ permalink, label, count, description, }: Props): JSX.Element;

package/lib/theme/Tag/index.js

@@ -8,10 +8,11 @@ import React from 'react';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import styles from './styles.module.css';
-export default function Tag({permalink, label, count}) {
+export default function Tag({permalink, label, count, description}) {
   return (
     <Link
       href={permalink}
+      title={description}
       className={clsx(
         styles.tag,
         count ? styles.tagWithCount : styles.tagRegular,

package/lib/theme/TagsListInline/index.js

@@ -20,9 +20,9 @@ export default function TagsListInline({tags}) {
         </Translate>
       </b>
       <ul className={clsx(styles.tags, 'padding--none', 'margin-left--sm')}>
-        {tags.map(({label, permalink: tagPermalink}) => (
-          <li key={tagPermalink} className={styles.tag}>
-            <Tag label={label} permalink={tagPermalink} />
+        {tags.map((tag) => (
+          <li key={tag.permalink} className={styles.tag}>
+            <Tag {...tag} />
           </li>
         ))}
       </ul>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "3.3.2",
+  "version": "3.4.0",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -20,18 +20,18 @@
     "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "dependencies": {
-    "@docusaurus/core": "3.3.2",
-    "@docusaurus/mdx-loader": "3.3.2",
-    "@docusaurus/module-type-aliases": "3.3.2",
-    "@docusaurus/plugin-content-blog": "3.3.2",
-    "@docusaurus/plugin-content-docs": "3.3.2",
-    "@docusaurus/plugin-content-pages": "3.3.2",
-    "@docusaurus/theme-common": "3.3.2",
-    "@docusaurus/theme-translations": "3.3.2",
-    "@docusaurus/types": "3.3.2",
-    "@docusaurus/utils": "3.3.2",
-    "@docusaurus/utils-common": "3.3.2",
-    "@docusaurus/utils-validation": "3.3.2",
+    "@docusaurus/core": "3.4.0",
+    "@docusaurus/mdx-loader": "3.4.0",
+    "@docusaurus/module-type-aliases": "3.4.0",
+    "@docusaurus/plugin-content-blog": "3.4.0",
+    "@docusaurus/plugin-content-docs": "3.4.0",
+    "@docusaurus/plugin-content-pages": "3.4.0",
+    "@docusaurus/theme-common": "3.4.0",
+    "@docusaurus/theme-translations": "3.4.0",
+    "@docusaurus/types": "3.4.0",
+    "@docusaurus/utils": "3.4.0",
+    "@docusaurus/utils-common": "3.4.0",
+    "@docusaurus/utils-validation": "3.4.0",
     "@mdx-js/react": "^3.0.0",
     "clsx": "^2.0.0",
     "copy-text-to-clipboard": "^3.2.0",
@@ -61,5 +61,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "bc638d674bfbde1e254ef306697f47e764b5e107"
+  "gitHead": "49e9a2143274a8dd795659b417b470bc42abbd6e"
 }

package/src/index.ts

@@ -10,6 +10,11 @@ import {createRequire} from 'module';
 import rtlcss from 'rtlcss';
 import {readDefaultCodeTranslationMessages} from '@docusaurus/theme-translations';
 import {getTranslationFiles, translateThemeConfig} from './translations';
+import {
+  getThemeInlineScript,
+  getAnnouncementBarInlineScript,
+  DataAttributeQueryStringInlineJavaScript,
+} from './inlineScripts';
 import type {LoadContext, Plugin} from '@docusaurus/types';
 import type {ThemeConfig} from '@docusaurus/theme-common';
 import type {Plugin as PostCssPlugin} from 'postcss';
@@ -23,97 +28,6 @@ const ContextReplacementPlugin = requireFromDocusaurusCore(
   'webpack/lib/ContextReplacementPlugin',
 ) as typeof webpack.ContextReplacementPlugin;
 
-// 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,
-  respectPrefersColorScheme,
-}: ThemeConfig['colorMode']) =>
-  /* language=js */
-  `(function() {
-  var defaultMode = '${defaultMode}';
-  var respectPrefersColorScheme = ${respectPrefersColorScheme};
-
-  function setDataThemeAttribute(theme) {
-    document.documentElement.setAttribute('data-theme', theme);
-  }
-
-  function getQueryStringTheme() {
-    try {
-      return new URLSearchParams(window.location.search).get('${ThemeQueryStringKey}')
-    } catch(e) {}
-  }
-
-  function getStoredTheme() {
-    try {
-      return localStorage.getItem('${ThemeStorageKey}');
-    } catch (err) {}
-  }
-
-  var initialTheme = getQueryStringTheme() || getStoredTheme();
-  if (initialTheme !== null) {
-    setDataThemeAttribute(initialTheme);
-  } else {
-    if (
-      respectPrefersColorScheme &&
-      window.matchMedia('(prefers-color-scheme: dark)').matches
-    ) {
-      setDataThemeAttribute('dark');
-    } else if (
-      respectPrefersColorScheme &&
-      window.matchMedia('(prefers-color-scheme: light)').matches
-    ) {
-      setDataThemeAttribute('light');
-    } else {
-      setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
-    }
-  }
-})();`;
-
-/* 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
-// + move all those announcementBar stuff there too
-export const AnnouncementBarDismissStorageKey =
-  'docusaurus.announcement.dismiss';
-const AnnouncementBarDismissDataAttribute =
-  'data-announcement-bar-initially-dismissed';
-// We always render the announcement bar html on the server, to prevent layout
-// shifts on React hydration. The theme can use CSS + the data attribute to hide
-// the announcement bar asap (before React hydration)
-/* language=js */
-const AnnouncementBarInlineJavaScript = `
-(function() {
-  function isDismissed() {
-    try {
-      return localStorage.getItem('${AnnouncementBarDismissStorageKey}') === 'true';
-    } catch (err) {}
-    return false;
-  }
-  document.documentElement.setAttribute('${AnnouncementBarDismissDataAttribute}', isDismissed());
-})();`;
-
 function getInfimaCSSFile(direction: string) {
   return `infima/dist/css/default/default${
     direction === 'rtl' ? '-rtl' : ''
@@ -126,6 +40,7 @@ export default function themeClassic(
 ): Plugin<undefined> {
   const {
     i18n: {currentLocale, localeConfigs},
+    siteStorage,
   } = context;
   const themeConfig = context.siteConfig.themeConfig as ThemeConfig;
   const {
@@ -218,9 +133,9 @@ export default function themeClassic(
           {
             tagName: 'script',
             innerHTML: `
-${noFlashColorMode(colorMode)}
+${getThemeInlineScript({colorMode, siteStorage})}
 ${DataAttributeQueryStringInlineJavaScript}
-${announcementBar ? AnnouncementBarInlineJavaScript : ''}
+${announcementBar ? getAnnouncementBarInlineScript({siteStorage}) : ''}
             `,
           },
         ],

package/src/inlineScripts.ts

@@ -0,0 +1,114 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {SiteStorage} from '@docusaurus/types';
+import type {ThemeConfig} from '@docusaurus/theme-common';
+
+// Support for ?docusaurus-theme=dark
+const ThemeQueryStringKey = 'docusaurus-theme';
+
+// Support for ?docusaurus-data-mode=embed&docusaurus-data-myAttr=42
+const DataQueryStringPrefixKey = 'docusaurus-data-';
+
+export function getThemeInlineScript({
+  colorMode: {defaultMode, respectPrefersColorScheme},
+  siteStorage,
+}: {
+  colorMode: ThemeConfig['colorMode'];
+  siteStorage: SiteStorage;
+}): string {
+  // Need to be inlined to prevent dark mode FOUC
+  // Make sure the key is the same as the one in the color mode React context
+  // Currently defined in: `docusaurus-theme-common/src/contexts/colorMode.tsx`
+  const themeStorageKey = `theme${siteStorage.namespace}`;
+
+  /* language=js */
+  return `(function() {
+    var defaultMode = '${defaultMode}';
+    var respectPrefersColorScheme = ${respectPrefersColorScheme};
+
+    function setDataThemeAttribute(theme) {
+      document.documentElement.setAttribute('data-theme', theme);
+    }
+
+    function getQueryStringTheme() {
+      try {
+        return new URLSearchParams(window.location.search).get('${ThemeQueryStringKey}')
+      } catch (e) {
+      }
+    }
+
+    function getStoredTheme() {
+      try {
+        return window['${siteStorage.type}'].getItem('${themeStorageKey}');
+      } catch (err) {
+      }
+    }
+
+    var initialTheme = getQueryStringTheme() || getStoredTheme();
+    if (initialTheme !== null) {
+      setDataThemeAttribute(initialTheme);
+    } else {
+      if (
+        respectPrefersColorScheme &&
+        window.matchMedia('(prefers-color-scheme: dark)').matches
+      ) {
+        setDataThemeAttribute('dark');
+      } else if (
+        respectPrefersColorScheme &&
+        window.matchMedia('(prefers-color-scheme: light)').matches
+      ) {
+        setDataThemeAttribute('light');
+      } else {
+        setDataThemeAttribute(defaultMode === 'dark' ? 'dark' : 'light');
+      }
+    }
+  })();`;
+}
+
+/* language=js */
+export 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) {}
+})();
+`;
+
+// We always render the announcement bar html on the server, to prevent layout
+// shifts on React hydration. The theme can use CSS + the data attribute to hide
+// the announcement bar asap (before React hydration)
+export function getAnnouncementBarInlineScript({
+  siteStorage,
+}: {
+  siteStorage: SiteStorage;
+}): string {
+  // 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 support Node.js with ESM support
+  // + move all those announcementBar stuff there too
+  const AnnouncementBarDismissStorageKey = `docusaurus.announcement.dismiss${siteStorage.namespace}`;
+  const AnnouncementBarDismissDataAttribute =
+    'data-announcement-bar-initially-dismissed';
+
+  /* language=js */
+  return `(function() {
+  function isDismissed() {
+    try {
+      return localStorage.getItem('${AnnouncementBarDismissStorageKey}') === 'true';
+    } catch (err) {}
+    return false;
+  }
+  document.documentElement.setAttribute('${AnnouncementBarDismissDataAttribute}', isDismissed());
+})();`;
+}

package/src/theme/BlogTagsPostsPage/index.tsx

@@ -57,7 +57,7 @@ function BlogTagsPostsPageMetadata({tag}: Props): JSX.Element {
   const title = useBlogTagsPostsPageTitle(tag);
   return (
     <>
-      <PageMetadata title={title} />
+      <PageMetadata title={title} description={tag.description} />
       <SearchMetadata tag="blog_tags_posts" />
     </>
   );
@@ -75,6 +75,7 @@ function BlogTagsPostsPageContent({
       {tag.unlisted && <Unlisted />}
       <header className="margin-bottom--xl">
         <Heading as="h1">{title}</Heading>
+        {tag.description && <p>{tag.description}</p>}
         <Link href={tag.allTagsPath}>
           <Translate
             id="theme.tags.tagsPageLink"

package/src/theme/DocCard/index.tsx

@@ -32,7 +32,7 @@ function useCategoryItemsPlural() {
       count,
       translate(
         {
-          message: '{count} items',
+          message: '1 item|{count} items',
           id: 'theme.docs.DocCard.categoryDescription.plurals',
           description:
             'The default description for a category card in the generated index about how many items this category includes',

package/src/theme/DocTagDocListPage/index.tsx

@@ -63,10 +63,11 @@ function DocItem({doc}: {doc: Props['tag']['items'][number]}): JSX.Element {
 
 function DocTagDocListPageMetadata({
   title,
+  tag,
 }: Props & {title: string}): JSX.Element {
   return (
     <>
-      <PageMetadata title={title} />
+      <PageMetadata title={title} description={tag.description} />
       <SearchMetadata tag="doc_tag_doc_list" />
     </>
   );
@@ -85,6 +86,7 @@ function DocTagDocListPageContent({
             {tag.unlisted && <Unlisted />}
             <header className="margin-bottom--xl">
               <Heading as="h1">{title}</Heading>
+              {tag.description && <p>{tag.description}</p>}
               <Link href={tag.allTagsPath}>
                 <Translate
                   id="theme.tags.tagsPageLink"

package/src/theme/Tag/index.tsx

@@ -12,10 +12,16 @@ import type {Props} from '@theme/Tag';
 
 import styles from './styles.module.css';
 
-export default function Tag({permalink, label, count}: Props): JSX.Element {
+export default function Tag({
+  permalink,
+  label,
+  count,
+  description,
+}: Props): JSX.Element {
   return (
     <Link
       href={permalink}
+      title={description}
       className={clsx(
         styles.tag,
         count ? styles.tagWithCount : styles.tagRegular,

package/src/theme/TagsListInline/index.tsx

@@ -24,9 +24,9 @@ export default function TagsListInline({tags}: Props): JSX.Element {
         </Translate>
       </b>
       <ul className={clsx(styles.tags, 'padding--none', 'margin-left--sm')}>
-        {tags.map(({label, permalink: tagPermalink}) => (
-          <li key={tagPermalink} className={styles.tag}>
-            <Tag label={label} permalink={tagPermalink} />
+        {tags.map((tag) => (
+          <li key={tag.permalink} className={styles.tag}>
+            <Tag {...tag} />
           </li>
         ))}
       </ul>