feat(theme): code block showLineNumbers=start metastring (#10846)

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

@@ -412,7 +412,7 @@ declare module '@theme/CodeBlock' {
     readonly metastring?: string;
     readonly title?: string;
     readonly language?: string;
-    readonly showLineNumbers?: boolean;
+    readonly showLineNumbers?: boolean | number;
   }
 
   export default function CodeBlock(props: Props): ReactNode;

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

@@ -12,7 +12,7 @@ import {
   parseCodeBlockTitle,
   parseLanguage,
   parseLines,
-  containsLineNumbers,
+  getLineNumbersStart,
   useCodeWordWrap,
 } from '@docusaurus/theme-common/internal';
 import {Highlight, type Language} from 'prism-react-renderer';
@@ -59,8 +59,10 @@ export default function CodeBlockString({
     language,
     magicComments,
   });
-  const showLineNumbers =
+  const lineNumbersStart = getLineNumbersStart({
-    showLineNumbersProp ?? containsLineNumbers(metastring);
+    showLineNumbers: showLineNumbersProp,
+    metastring,
+  });
 
   return (
     <Container
@@ -87,8 +89,14 @@ export default function CodeBlockString({
               <code
                 className={clsx(
                   styles.codeBlockLines,
-                  showLineNumbers && styles.codeBlockLinesWithNumbering,
+                  lineNumbersStart !== undefined &&
-                )}>
+                    styles.codeBlockLinesWithNumbering,
+                )}
+                style={
+                  lineNumbersStart === undefined
+                    ? undefined
+                    : {counterReset: `line-count ${lineNumbersStart - 1}`}
+                }>
                 {tokens.map((line, i) => (
                   <Line
                     key={i}
@@ -96,7 +104,7 @@ export default function CodeBlockString({
                     getLineProps={getLineProps}
                     getTokenProps={getTokenProps}
                     classNames={lineClassNames[i]}
-                    showLineNumbers={showLineNumbers}
+                    showLineNumbers={lineNumbersStart !== undefined}
                   />
                 ))}
               </code>

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

@@ -37,7 +37,7 @@ export {
   parseCodeBlockTitle,
   parseLanguage,
   parseLines,
-  containsLineNumbers,
+  getLineNumbersStart,
 } from './utils/codeBlockUtils';
 
 export {DEFAULT_SEARCH_TAG} from './utils/searchUtils';

packages/docusaurus-theme-common/src/utils/codeBlockUtils.ts

@@ -151,8 +151,37 @@ export function parseCodeBlockTitle(metastring?: string): string {
   return metastring?.match(codeBlockTitleRegex)?.groups!.title ?? '';
 }
 
-export function containsLineNumbers(metastring?: string): boolean {
+function getMetaLineNumbersStart(metastring?: string): number | undefined {
-  return Boolean(metastring?.includes('showLineNumbers'));
+  const showLineNumbersMeta = metastring
+    ?.split(' ')
+    .find((str) => str.startsWith('showLineNumbers'));
+
+  if (showLineNumbersMeta) {
+    if (showLineNumbersMeta.startsWith('showLineNumbers=')) {
+      const value = showLineNumbersMeta.replace('showLineNumbers=', '');
+      return parseInt(value, 10);
+    }
+    return 1;
+  }
+
+  return undefined;
+}
+
+export function getLineNumbersStart({
+  showLineNumbers,
+  metastring,
+}: {
+  showLineNumbers: boolean | number | undefined;
+  metastring: string | undefined;
+}): number | undefined {
+  const defaultStart = 1;
+  if (typeof showLineNumbers === 'boolean') {
+    return showLineNumbers ? defaultStart : undefined;
+  }
+  if (typeof showLineNumbers === 'number') {
+    return showLineNumbers;
+  }
+  return getMetaLineNumbersStart(metastring);
 }
 
 /**

website/docs/guides/markdown-features/markdown-features-code-blocks.mdx

@@ -395,18 +395,12 @@ The `Line` component will receive the list of class names, based on which you ca
 You can enable line numbering for your code block by using `showLineNumbers` key within the language meta string (don't forget to add space directly before the key).
 
 ````md
-```jsx {1,4-6,11} showLineNumbers
+```jsx showLineNumbers
 import React from 'react';
 
-function MyComponent(props) {
+export default function MyComponent(props) {
-  if (props.isBar) {
-    return <div>Bar</div>;
-  }
-
   return <div>Foo</div>;
 }
-
-export default MyComponent;
 ```
 ````
 
@@ -414,18 +408,36 @@ export default MyComponent;
 <BrowserWindow>
 ```
 
-```jsx {1,4-6,11} showLineNumbers
+```jsx showLineNumbers
 import React from 'react';
 
-function MyComponent(props) {
+export default function MyComponent(props) {
-  if (props.isBar) {
-    return <div>Bar</div>;
-  }
-
   return <div>Foo</div>;
 }
+```
 
-export default MyComponent;
+```mdx-code-block
+</BrowserWindow>
+```
+
+By default, the counter starts at line number 1. It's possible to pass a custom counter start value to split large code blocks for readability:
+
+````md
+```jsx showLineNumbers=3
+export default function MyComponent(props) {
+  return <div>Foo</div>;
+}
+```
+````
+
+```mdx-code-block
+<BrowserWindow>
+```
+
+```jsx showLineNumbers=3
+export default function MyComponent(props) {
+  return <div>Foo</div>;
+}
 ```
 
 ```mdx-code-block