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

Author: Danielku15

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,6 +482,7 @@ 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;
   }

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-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,