feat(theme-common, theme-classic): Improve CodeBlock Extensibility

packages/docusaurus-theme-classic/src/theme-classic.d.ts

@@ -405,11 +405,12 @@ declare module '@theme/BlogLayout' {
 
 declare module '@theme/CodeBlock' {
   import type {ReactNode} from 'react';
+  import type {CodeBlockMeta} from '@docusaurus/theme-common';
 
   export interface Props {
     readonly children: ReactNode;
     readonly className?: string;
-    readonly metastring?: string;
+    readonly metastring?: string | CodeBlockMeta;
     readonly title?: ReactNode;
     readonly language?: string;
     readonly showLineNumbers?: boolean | number;
@@ -481,13 +482,26 @@ declare module '@theme/CodeBlock/Line' {
     readonly line: Token[];
     readonly classNames: string[] | undefined;
     readonly showLineNumbers: boolean;
+    readonly meta?: CodeBlockMeta;
     readonly getLineProps: (input: LineInputProps) => LineOutputProps;
     readonly getTokenProps: (input: TokenInputProps) => TokenOutputProps;
   }
 
   export default function CodeBlockLine(props: Props): ReactNode;
 }
 
+declare module '@theme/CodeBlock/Token' {
+  import type {ReactNode} from 'react';
+  import type {TokenOutputProps} from 'prism-react-renderer';
+
+  export interface Props {
+    readonly output: TokenOutputProps;
+    readonly meta?: CodeBlockMeta;
+  }
+
+  export default function CodeBlockToken(props: Props): ReactNode;
+}
+
 declare module '@theme/CodeBlock/WordWrapButton' {
   import type {ReactNode} from 'react';
 

packages/docusaurus-theme-classic/src/theme/CodeBlock/Content/String.tsx

@@ -9,7 +9,6 @@ import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
 import {useThemeConfig, usePrismTheme} from '@docusaurus/theme-common';
 import {
-  parseCodeBlockTitle,
   parseLanguage,
   parseLines,
   getLineNumbersStart,
@@ -51,19 +50,19 @@ export default function CodeBlockString({
   const wordWrap = useCodeWordWrap();
   const isBrowser = useIsBrowser();
 
-  // We still parse the metastring in case we want to support more syntax in the
-  // future. Note that MDX doesn't strip quotes when parsing metastring:
-  // "title=\"xyz\"" => title: "\"xyz\""
-  const title = parseCodeBlockTitle(metastring) || titleProp;
-
-  const {lineClassNames, code} = parseLines(children, {
+  const {meta, code} = parseLines(children, {
     metastring,
     language,
     magicComments,
   });
+
+  // Note that MDX doesn't strip quotes when parsing metastring:
+  // "title=\"xyz\"" => title: "\"xyz\""
+  const title = meta.options.title ?? titleProp;
+
   const lineNumbersStart = getLineNumbersStart({
     showLineNumbers: showLineNumbersProp,
-    metastring,
+    meta,
   });
 
   return (
@@ -105,7 +104,8 @@ export default function CodeBlockString({
                     line={line}
                     getLineProps={getLineProps}
                     getTokenProps={getTokenProps}
-                    classNames={lineClassNames[i]}
+                    classNames={meta.lineClassNames[i]}
+                    meta={meta}
                     showLineNumbers={lineNumbersStart !== undefined}
                   />
                 ))}

packages/docusaurus-theme-classic/src/theme/CodeBlock/Line/index.tsx

@@ -9,6 +9,7 @@ import React, {type ReactNode} from 'react';
 import clsx from 'clsx';
 import type {Props} from '@theme/CodeBlock/Line';
 
+import CodeBlockToken from '@theme/CodeBlock/Token';
 import styles from './styles.module.css';
 
 type Token = Props['line'][number];
@@ -41,7 +42,7 @@ export default function CodeBlockLine({
   });
 
   const lineTokens = line.map((token, key) => (
-    <span key={key} {...getTokenProps({token})} />
+    <CodeBlockToken key={key} output={getTokenProps({token})} />
   ));
 
   return (

packages/docusaurus-theme-classic/src/theme/CodeBlock/Token/index.tsx

@@ -0,0 +1,13 @@
+/**
+ * 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 React, {type ReactNode} from 'react';
+import type {Props} from '@theme/CodeBlock/Token';
+
+export default function CodeBlockToken({output}: Props): ReactNode {
+  return <span {...output} />;
+}

packages/docusaurus-theme-common/src/index.ts

@@ -144,3 +144,8 @@ export {
   ErrorBoundaryErrorMessageFallback,
   ErrorCauseBoundary,
 } from './utils/errorBoundaryUtils';
+
+export {
+  type CodeBlockMeta,
+  type CodeMetaOptionValue,
+} from './utils/codeBlockUtils';

packages/docusaurus-theme-common/src/internal.ts

@@ -34,7 +34,7 @@ export {ColorModeProvider} from './contexts/colorMode';
 export {useAlternatePageUtils} from './utils/useAlternatePageUtils';
 
 export {
-  parseCodeBlockTitle,
+  parseCodeBlockMeta,
   parseLanguage,
   parseLines,
   getLineNumbersStart,