@docusaurus/theme-classic 0.0.0-4951 → 0.0.0-4954

package/lib/theme-classic.d.ts

@@ -219,7 +219,7 @@ declare module '@theme/CodeBlock/Line' {
 
   export interface Props {
     readonly line: Token[];
-    readonly highlight: boolean;
+    readonly classNames: string[] | undefined;
     readonly showLineNumbers: boolean;
     readonly getLineProps: GetLineProps;
     readonly getTokenProps: GetTokenProps;

package/lib/validateThemeConfig.js

@@ -19,11 +19,19 @@ function _interopRequireDefault(obj) { return obj && obj.__esModule ? obj : { de
  * LICENSE file in the root directory of this source tree.
  */
 const DEFAULT_DOCS_CONFIG = {
-  versionPersistence: 'localStorage'
+  versionPersistence: 'localStorage',
+  sidebar: {
+    hideable: false,
+    autoCollapseCategories: false
+  }
 };
 
 const DocsSchema = _utilsValidation.Joi.object({
-  versionPersistence: _utilsValidation.Joi.string().equal('localStorage', 'none').default(DEFAULT_DOCS_CONFIG.versionPersistence)
+  versionPersistence: _utilsValidation.Joi.string().equal('localStorage', 'none').default(DEFAULT_DOCS_CONFIG.versionPersistence),
+  sidebar: _utilsValidation.Joi.object({
+    hideable: _utilsValidation.Joi.bool().default(DEFAULT_DOCS_CONFIG.sidebar.hideable),
+    autoCollapseCategories: _utilsValidation.Joi.bool().default(DEFAULT_DOCS_CONFIG.sidebar.autoCollapseCategories)
+  }).default(DEFAULT_DOCS_CONFIG.sidebar)
 }).default(DEFAULT_DOCS_CONFIG);
 
 const DEFAULT_COLOR_MODE_CONFIG = {
@@ -37,14 +45,20 @@ const DEFAULT_CONFIG = {
   metadata: [],
   prism: {
     additionalLanguages: [],
-    theme: _palenight.default
+    theme: _palenight.default,
+    magicComments: [{
+      className: 'theme-code-block-highlighted-line',
+      line: 'highlight-next-line',
+      block: {
+        start: 'highlight-start',
+        end: 'highlight-end'
+      }
+    }]
   },
   navbar: {
     hideOnScroll: false,
     items: []
   },
-  hideableSidebar: false,
-  autoCollapseSidebarCategories: false,
   tableOfContents: {
     minHeadingLevel: 2,
     maxHeadingLevel: 3
@@ -314,10 +328,22 @@ const ThemeConfigSchema = _utilsValidation.Joi.object({
       styles: _utilsValidation.Joi.alternatives().try(_utilsValidation.Joi.array(), _utilsValidation.Joi.object()).required()
     }),
     defaultLanguage: _utilsValidation.Joi.string(),
-    additionalLanguages: _utilsValidation.Joi.array().items(_utilsValidation.Joi.string()).default(DEFAULT_CONFIG.prism.additionalLanguages)
+    additionalLanguages: _utilsValidation.Joi.array().items(_utilsValidation.Joi.string()).default(DEFAULT_CONFIG.prism.additionalLanguages),
+    magicComments: _utilsValidation.Joi.array().items(_utilsValidation.Joi.object({
+      className: _utilsValidation.Joi.string().required(),
+      line: _utilsValidation.Joi.string(),
+      block: _utilsValidation.Joi.object({
+        start: _utilsValidation.Joi.string().required(),
+        end: _utilsValidation.Joi.string().required()
+      })
+    }).or('line', 'block')).default(DEFAULT_CONFIG.prism.magicComments)
   }).default(DEFAULT_CONFIG.prism).unknown(),
-  hideableSidebar: _utilsValidation.Joi.bool().default(DEFAULT_CONFIG.hideableSidebar),
-  autoCollapseSidebarCategories: _utilsValidation.Joi.bool().default(DEFAULT_CONFIG.autoCollapseSidebarCategories),
+  hideableSidebar: _utilsValidation.Joi.forbidden().messages({
+    'any.unknown': 'themeConfig.hideableSidebar has been moved to themeConfig.docs.sidebar.hideable.'
+  }),
+  autoCollapseSidebarCategories: _utilsValidation.Joi.forbidden().messages({
+    'any.unknown': 'themeConfig.autoCollapseSidebarCategories has been moved to themeConfig.docs.sidebar.autoCollapseCategories.'
+  }),
   sidebarCollapsible: _utilsValidation.Joi.forbidden().messages({
     'any.unknown': 'The themeConfig.sidebarCollapsible has been moved to docs plugin options. See: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs'
   }),

package/lib-next/theme/CodeBlock/Content/String.js

@@ -30,7 +30,7 @@ export default function CodeBlockString({
   language: languageProp,
 }) {
   const {
-    prism: {defaultLanguage},
+    prism: {defaultLanguage, magicComments},
   } = useThemeConfig();
   const language =
     languageProp ?? parseLanguage(blockClassName) ?? defaultLanguage;
@@ -40,7 +40,11 @@ export default function CodeBlockString({
   // "title=\"xyz\"" => title: "\"xyz\""
 
   const title = parseCodeBlockTitle(metastring) || titleProp;
-  const {highlightLines, code} = parseLines(children, metastring, language);
+  const {lineClassNames, code} = parseLines(children, {
+    metastring,
+    language,
+    magicComments,
+  });
   const showLineNumbers =
     showLineNumbersProp || containsLineNumbers(metastring);
   return (
@@ -76,7 +80,7 @@ export default function CodeBlockString({
                     line={line}
                     getLineProps={getLineProps}
                     getTokenProps={getTokenProps}
-                    highlight={highlightLines.includes(i)}
+                    classNames={lineClassNames[i]}
                     showLineNumbers={showLineNumbers}
                   />
                 ))}

package/lib-next/theme/CodeBlock/Line/index.js

@@ -9,7 +9,7 @@ import clsx from 'clsx';
 import styles from './styles.module.css';
 export default function CodeBlockLine({
   line,
-  highlight,
+  classNames,
   showLineNumbers,
   getLineProps,
   getTokenProps,
@@ -20,19 +20,8 @@ export default function CodeBlockLine({
 
   const lineProps = getLineProps({
     line,
-    ...(showLineNumbers && {
-      className: styles.codeLine,
-    }),
+    className: clsx(classNames, showLineNumbers && styles.codeLine),
   });
-
-  if (highlight) {
-    lineProps.className = clsx(
-      lineProps.className,
-      styles.highlightedCodeLine,
-      'theme-code-block-highlighted-line',
-    );
-  }
-
   const lineTokens = line.map((token, key) => (
     <span
       key={key}

package/lib-next/theme/CodeBlock/Line/styles.module.css

@@ -5,6 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+:global(.theme-code-block-highlighted-line) {
+  background-color: var(--docusaurus-highlighted-code-line-bg);
+  display: block;
+  margin: 0 calc(-1 * var(--ifm-pre-padding));
+  padding: 0 var(--ifm-pre-padding);
+}
+
 /* Intentionally has zero specificity, so that to be able to override
 the background in custom CSS file due bug https://github.com/facebook/docusaurus/issues/3678 */
 :where(:root) {
@@ -15,13 +22,6 @@ the background in custom CSS file due bug https://github.com/facebook/docusaurus
   --docusaurus-highlighted-code-line-bg: rgb(100 100 100);
 }
 
-.highlightedCodeLine {
-  background-color: var(--docusaurus-highlighted-code-line-bg);
-  display: block;
-  margin: 0 calc(-1 * var(--ifm-pre-padding));
-  padding: 0 var(--ifm-pre-padding);
-}
-
 .codeLine {
   display: table-row;
   counter-increment: line-count;

package/lib-next/theme/DocSidebar/Desktop/index.js

@@ -15,7 +15,9 @@ import styles from './styles.module.css';
 function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}) {
   const {
     navbar: {hideOnScroll},
-    hideableSidebar,
+    docs: {
+      sidebar: {hideable},
+    },
   } = useThemeConfig();
   return (
     <div
@@ -26,7 +28,7 @@ function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}) {
       )}>
       {hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
       <Content path={path} sidebar={sidebar} />
-      {hideableSidebar && <CollapseButton onClick={onCollapse} />}
+      {hideable && <CollapseButton onClick={onCollapse} />}
     </div>
   );
 }

package/lib-next/theme/DocSidebarItem/Category.js

@@ -114,23 +114,21 @@ export default function DocSidebarItemCategory({
     setCollapsed(toCollapsed);
   }
 
-  const {autoCollapseSidebarCategories} = useThemeConfig();
+  const {
+    docs: {
+      sidebar: {autoCollapseCategories},
+    },
+  } = useThemeConfig();
   useEffect(() => {
     if (
       collapsible &&
       expandedItem &&
       expandedItem !== index &&
-      autoCollapseSidebarCategories
+      autoCollapseCategories
     ) {
       setCollapsed(true);
     }
-  }, [
-    collapsible,
-    expandedItem,
-    index,
-    setCollapsed,
-    autoCollapseSidebarCategories,
-  ]);
+  }, [collapsible, expandedItem, index, setCollapsed, autoCollapseCategories]);
   return (
     <li
       className={clsx(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "0.0.0-4951",
+  "version": "0.0.0-4954",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -21,15 +21,15 @@
     "format:lib-next": "prettier --config ../../.prettierrc --write \"lib-next/**/*.{js,ts,jsx,tsc}\""
   },
   "dependencies": {
-    "@docusaurus/core": "0.0.0-4951",
-    "@docusaurus/plugin-content-blog": "0.0.0-4951",
-    "@docusaurus/plugin-content-docs": "0.0.0-4951",
-    "@docusaurus/plugin-content-pages": "0.0.0-4951",
-    "@docusaurus/theme-common": "0.0.0-4951",
-    "@docusaurus/theme-translations": "0.0.0-4951",
-    "@docusaurus/utils": "0.0.0-4951",
-    "@docusaurus/utils-common": "0.0.0-4951",
-    "@docusaurus/utils-validation": "0.0.0-4951",
+    "@docusaurus/core": "0.0.0-4954",
+    "@docusaurus/plugin-content-blog": "0.0.0-4954",
+    "@docusaurus/plugin-content-docs": "0.0.0-4954",
+    "@docusaurus/plugin-content-pages": "0.0.0-4954",
+    "@docusaurus/theme-common": "0.0.0-4954",
+    "@docusaurus/theme-translations": "0.0.0-4954",
+    "@docusaurus/utils": "0.0.0-4954",
+    "@docusaurus/utils-common": "0.0.0-4954",
+    "@docusaurus/utils-validation": "0.0.0-4954",
     "@mdx-js/react": "^1.6.22",
     "clsx": "^1.1.1",
     "copy-text-to-clipboard": "^3.0.1",
@@ -46,8 +46,8 @@
     "@babel/cli": "^7.17.10",
     "@babel/core": "^7.17.10",
     "@babel/preset-typescript": "^7.16.7",
-    "@docusaurus/module-type-aliases": "0.0.0-4951",
-    "@docusaurus/types": "0.0.0-4951",
+    "@docusaurus/module-type-aliases": "0.0.0-4954",
+    "@docusaurus/types": "0.0.0-4954",
     "@types/mdx-js__react": "^1.5.5",
     "@types/nprogress": "^0.2.0",
     "@types/prismjs": "^1.26.0",
@@ -64,5 +64,5 @@
   "engines": {
     "node": ">=14"
   },
-  "gitHead": "d3321f8bb35b07061d37fffea81392b0cd3b63ed"
+  "gitHead": "858b548c9cda08f8405325e1651c9f4234eabb34"
 }

package/src/theme/CodeBlock/Content/String.tsx

@@ -34,7 +34,7 @@ export default function CodeBlockString({
   language: languageProp,
 }: Props): JSX.Element {
   const {
-    prism: {defaultLanguage},
+    prism: {defaultLanguage, magicComments},
   } = useThemeConfig();
   const language =
     languageProp ?? parseLanguage(blockClassName) ?? defaultLanguage;
@@ -46,7 +46,11 @@ export default function CodeBlockString({
   // "title=\"xyz\"" => title: "\"xyz\""
   const title = parseCodeBlockTitle(metastring) || titleProp;
 
-  const {highlightLines, code} = parseLines(children, metastring, language);
+  const {lineClassNames, code} = parseLines(children, {
+    metastring,
+    language,
+    magicComments,
+  });
   const showLineNumbers =
     showLineNumbersProp || containsLineNumbers(metastring);
 
@@ -83,7 +87,7 @@ export default function CodeBlockString({
                     line={line}
                     getLineProps={getLineProps}
                     getTokenProps={getTokenProps}
-                    highlight={highlightLines.includes(i)}
+                    classNames={lineClassNames[i]}
                     showLineNumbers={showLineNumbers}
                   />
                 ))}

package/src/theme/CodeBlock/Line/index.tsx

@@ -12,7 +12,7 @@ import styles from './styles.module.css';
 
 export default function CodeBlockLine({
   line,
-  highlight,
+  classNames,
   showLineNumbers,
   getLineProps,
   getTokenProps,
@@ -23,17 +23,9 @@ export default function CodeBlockLine({
 
   const lineProps = getLineProps({
     line,
-    ...(showLineNumbers && {className: styles.codeLine}),
+    className: clsx(classNames, showLineNumbers && styles.codeLine),
   });
 
-  if (highlight) {
-    lineProps.className = clsx(
-      lineProps.className,
-      styles.highlightedCodeLine,
-      'theme-code-block-highlighted-line',
-    );
-  }
-
   const lineTokens = line.map((token, key) => (
     <span key={key} {...getTokenProps({token, key})} />
   ));

package/src/theme/CodeBlock/Line/styles.module.css

@@ -5,6 +5,13 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+:global(.theme-code-block-highlighted-line) {
+  background-color: var(--docusaurus-highlighted-code-line-bg);
+  display: block;
+  margin: 0 calc(-1 * var(--ifm-pre-padding));
+  padding: 0 var(--ifm-pre-padding);
+}
+
 /* Intentionally has zero specificity, so that to be able to override
 the background in custom CSS file due bug https://github.com/facebook/docusaurus/issues/3678 */
 :where(:root) {
@@ -15,13 +22,6 @@ the background in custom CSS file due bug https://github.com/facebook/docusaurus
   --docusaurus-highlighted-code-line-bg: rgb(100 100 100);
 }
 
-.highlightedCodeLine {
-  background-color: var(--docusaurus-highlighted-code-line-bg);
-  display: block;
-  margin: 0 calc(-1 * var(--ifm-pre-padding));
-  padding: 0 var(--ifm-pre-padding);
-}
-
 .codeLine {
   display: table-row;
   counter-increment: line-count;

package/src/theme/DocSidebar/Desktop/index.tsx

@@ -18,7 +18,9 @@ import styles from './styles.module.css';
 function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
   const {
     navbar: {hideOnScroll},
-    hideableSidebar,
+    docs: {
+      sidebar: {hideable},
+    },
   } = useThemeConfig();
 
   return (
@@ -30,7 +32,7 @@ function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
       )}>
       {hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
       <Content path={path} sidebar={sidebar} />
-      {hideableSidebar && <CollapseButton onClick={onCollapse} />}
+      {hideable && <CollapseButton onClick={onCollapse} />}
     </div>
   );
 }

package/src/theme/DocSidebarItem/Category.tsx

@@ -127,23 +127,21 @@ export default function DocSidebarItemCategory({
     setExpandedItem(toCollapsed ? null : index);
     setCollapsed(toCollapsed);
   }
-  const {autoCollapseSidebarCategories} = useThemeConfig();
+  const {
+    docs: {
+      sidebar: {autoCollapseCategories},
+    },
+  } = useThemeConfig();
   useEffect(() => {
     if (
       collapsible &&
       expandedItem &&
       expandedItem !== index &&
-      autoCollapseSidebarCategories
+      autoCollapseCategories
     ) {
       setCollapsed(true);
     }
-  }, [
-    collapsible,
-    expandedItem,
-    index,
-    setCollapsed,
-    autoCollapseSidebarCategories,
-  ]);
+  }, [collapsible, expandedItem, index, setCollapsed, autoCollapseCategories]);
 
   return (
     <li

package/src/theme-classic.d.ts

@@ -219,7 +219,7 @@ declare module '@theme/CodeBlock/Line' {
 
   export interface Props {
     readonly line: Token[];
-    readonly highlight: boolean;
+    readonly classNames: string[] | undefined;
     readonly showLineNumbers: boolean;
     readonly getLineProps: GetLineProps;
     readonly getTokenProps: GetTokenProps;

package/src/validateThemeConfig.ts

@@ -14,11 +14,21 @@ import type {
 
 const DEFAULT_DOCS_CONFIG = {
   versionPersistence: 'localStorage',
+  sidebar: {
+    hideable: false,
+    autoCollapseCategories: false,
+  },
 };
 const DocsSchema = Joi.object({
   versionPersistence: Joi.string()
     .equal('localStorage', 'none')
     .default(DEFAULT_DOCS_CONFIG.versionPersistence),
+  sidebar: Joi.object({
+    hideable: Joi.bool().default(DEFAULT_DOCS_CONFIG.sidebar.hideable),
+    autoCollapseCategories: Joi.bool().default(
+      DEFAULT_DOCS_CONFIG.sidebar.autoCollapseCategories,
+    ),
+  }).default(DEFAULT_DOCS_CONFIG.sidebar),
 }).default(DEFAULT_DOCS_CONFIG);
 
 const DEFAULT_COLOR_MODE_CONFIG = {
@@ -34,13 +44,18 @@ export const DEFAULT_CONFIG = {
   prism: {
     additionalLanguages: [],
     theme: defaultPrismTheme,
+    magicComments: [
+      {
+        className: 'theme-code-block-highlighted-line',
+        line: 'highlight-next-line',
+        block: {start: 'highlight-start', end: 'highlight-end'},
+      },
+    ],
   },
   navbar: {
     hideOnScroll: false,
     items: [],
   },
-  hideableSidebar: false,
-  autoCollapseSidebarCategories: false,
   tableOfContents: {
     minHeadingLevel: 2,
     maxHeadingLevel: 3,
@@ -378,13 +393,29 @@ export const ThemeConfigSchema = Joi.object({
     additionalLanguages: Joi.array()
       .items(Joi.string())
       .default(DEFAULT_CONFIG.prism.additionalLanguages),
+    magicComments: Joi.array()
+      .items(
+        Joi.object({
+          className: Joi.string().required(),
+          line: Joi.string(),
+          block: Joi.object({
+            start: Joi.string().required(),
+            end: Joi.string().required(),
+          }),
+        }).or('line', 'block'),
+      )
+      .default(DEFAULT_CONFIG.prism.magicComments),
   })
     .default(DEFAULT_CONFIG.prism)
     .unknown(),
-  hideableSidebar: Joi.bool().default(DEFAULT_CONFIG.hideableSidebar),
-  autoCollapseSidebarCategories: Joi.bool().default(
-    DEFAULT_CONFIG.autoCollapseSidebarCategories,
-  ),
+  hideableSidebar: Joi.forbidden().messages({
+    'any.unknown':
+      'themeConfig.hideableSidebar has been moved to themeConfig.docs.sidebar.hideable.',
+  }),
+  autoCollapseSidebarCategories: Joi.forbidden().messages({
+    'any.unknown':
+      'themeConfig.autoCollapseSidebarCategories has been moved to themeConfig.docs.sidebar.autoCollapseCategories.',
+  }),
   sidebarCollapsible: Joi.forbidden().messages({
     'any.unknown':
       'The themeConfig.sidebarCollapsible has been moved to docs plugin options. See: https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs',