refactor(theme-common, theme-classic, theme-live-codeblock): Parse `metastring` into `metaOptions` and use it across components #11019

Danielku15 · 2025-03-22T17:02:33Z

Pre-flight checklist

I have read the Contributing Guidelines on pull requests.
If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
If this is a new API or substantial change: the PR has an accompanying issue (closes #0000) and the maintainers have approved on my working plan.

Motivation

This PR is part of a series related to #11008 and it superceeds #11011 in the goal to splitup the work into more isolated refactoring/feature parts.

Note that this PR also includes the changes of previous steps and therefore the overall diff can be misleading. The best approach will be to review and merge every step individually and then rebase accordingly.

Intermediately the specific changes can be checked here: Danielku15/docusaurus@feature/codeblock-meta...Danielku15:docusaurus:feature/codeblock-meta-2

Step 1 (#11017): Splitup current parseLines logic (separation of concerns)
Step 2 (this PR): Parse metastring into metaOptions and use it across components.
Step 3 (#11021): Add parsing of any options specified in the metastring.
Step 4 (#11022): Add CodeBlockToken component to customize DOM of highlighted tokens.
Step 5 (#11023): Pass metaOptions to whole codeblock component tree.

The motivation of this part is to centralize the metastring parsing across components to a central location without changing the parsing logic itself.

To achieve the central parsing a new metaOptions is introduced and the old inline logic is adapted everywhere.

Due to the way the live code editor works the metaOptions is introduced as component prop. This way we can parse it once and pass it through. The possible overlap between prop<->metaOptions is the same like prop<->metastring before.

We could split this PR further but I think it makes sense to update all components to use metaOptions in one go. The refactoring per component of clearly visible in individual commits.

Test Plan

Automatic testing relies on existing integration tests.

Manual testing by checking /docs/markdown-features/code-blocks showed no impact of the change.

Test links

Deploy preview: https://deploy-preview-11019--docusaurus-2.netlify.app
Code Blocks: https://deploy-preview-11019--docusaurus-2.netlify.app/docs/markdown-features/code-blocks/

Related issues/PRs

netlify · 2025-03-22T17:05:12Z

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	`7136e71`
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/67e7ef6e3ad50a0008056e9a
😎 Deploy Preview	https://deploy-preview-11019--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

github-actions · 2025-03-22T17:08:00Z

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	Report
/	🔴 41	🟢 98	🟢 100	🟢 100	Report
/docs/installation	🔴 49	🟢 97	🟢 100	🟢 100	Report
/docs/category/getting-started	🟠 71	🟢 100	🟢 100	🟠 86	Report
/blog	🟠 63	🟢 96	🟢 100	🟠 86	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 62	🟢 92	🟢 100	🟢 100	Report
/blog/tags/release	🟠 63	🟢 96	🟢 100	🟠 86	Report
/blog/tags	🟠 73	🟢 100	🟢 100	🟠 86	Report

slorber · 2025-03-28T11:47:17Z

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

+/**
+ * The supported types for {@link CodeBlockMetaOptions} values.
+ */
+export type CodeMetaOptionValue = string | number | boolean | undefined;
+
+/**
+ * A property bag for custom options specified by the user via metastring
+ * to control aspects like title and line numbers.
+ */
+export type CodeBlockMetaOptions = {
+  [key: string]: CodeMetaOptionValue;
+};


This is not typesafe, we'd rather use an interface as explained here #11011 (comment)

slorber · 2025-03-28T11:49:05Z

packages/docusaurus-theme-live-codeblock/src/theme/CodeBlock/index.tsx

 import Playground from '@theme/Playground';
 import ReactLiveScope from '@theme/ReactLiveScope';
 import CodeBlock, {type Props} from '@theme-init/CodeBlock';

 const withLiveEditor = (Component: typeof CodeBlock) => {
  function WrappedComponent(props: Props) {
-    if (props.live) {
-      return <Playground scope={ReactLiveScope} {...props} />;
+    const metaOptions = parseCodeBlockMetaOptions(


Isn't this going to lead to parsing 3 times the metastring?

We don't want to parse it for:

the live code block

the code block

the playground

We only want to parse options once

No, I tried to ensure we parse it only once. Its a bit explained in the PR motivation:

Due to the way the live code editor works the metaOptions is introduced as component prop. This way we can parse it once and pass it through. The possible overlap between prop<->metaOptions is the same like prop<->metastring before.

I added a new metaOptions prop for this purpose to pass it from parent to child when possible. The forwarding is happening here in line 26 and 32.

parseCodeBlockMetaOptions prioritizes the bag from the props if available.

slorber · 2025-03-28T11:55:16Z

packages/docusaurus-theme-live-codeblock/src/theme/CodeBlock/index.tsx

 import Playground from '@theme/Playground';
 import ReactLiveScope from '@theme/ReactLiveScope';
 import CodeBlock, {type Props} from '@theme-init/CodeBlock';

 const withLiveEditor = (Component: typeof CodeBlock) => {
  function WrappedComponent(props: Props) {
-    if (props.live) {


I'd like to keep it for retrocompatibility

The prop is still there (see line 21)

slorber · 2025-03-28T11:57:38Z

packages/docusaurus-mdx-loader/src/remark/mdx1Compat/codeCompatPlugin.ts

-
-      // Retrocompatible support for live codeblock metastring
-      // Not really the appropriate place to handle that :s
-      node.data.hProperties.live = node.meta?.split(' ').includes('live');


Historically, with MDX 1 (Docusaurus v2), the live code block component would receive a "live" prop.

Our users have swizzled the live code block component, so if you remove this line, their component won't receive the live=true prop anymore and it might break their site. I'd prefer to keep it, and eventually only remove this for Docusaurus v4.

Thanks for the further insight. This area was a bit sensitive for me as I wasn't sure about all the affected parts (also considering the note above in line 17).

The normal @theme/CodeBlock doesn't have a live property, it only comes via docusaurus-theme-live-codeblock (as @theme-init/CodeBlock) And I thought there users would rather swizzle the Playground component.

I didn't try all scenarios, but normally swizzling a CodeBlock gives you props without live. But it might be risky that people might have relied on a hidden live property in older code and declared a live property themselves.

Unfortunately this is the docusaurus-mdx-loader package which has no access to the codeBlockUtils. So we would need to keep this code as it is. I don't think we can rely on the metaOptions easily.

Danielku15 · 2025-03-28T17:11:17Z

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

+  // we keep the old custom logic which was moved from their old spots to here.
+
+  // normal codeblock
+  const title = metastring?.match(codeBlockTitleRegex)?.groups!.title;


Pre-existing code was just moved. Regex pattern and input values are unchanged.

… metaOptions

…nline

…mbers

slorber · 2025-04-04T18:17:48Z

Added, see #11017 (comment)

facebook-github-bot added the CLA Signed Signed Facebook CLA label Mar 22, 2025

Danielku15 mentioned this pull request Mar 22, 2025

test(theme-common): Add tests for getLineNumbersStart #11017

Merged

3 tasks

Danielku15 force-pushed the feature/codeblock-meta-2 branch from 2d0eeef to 29d2c19 Compare March 22, 2025 17:11

slorber requested changes Mar 28, 2025

View reviewed changes

Danielku15 force-pushed the feature/codeblock-meta-2 branch 2 times, most recently from 0b4addf to f8b3736 Compare March 28, 2025 17:03

github-advanced-security bot found potential problems Mar 28, 2025

View reviewed changes

Danielku15 added 6 commits March 28, 2025 18:18

refactor(theme-classic, theme-common): Parse CodeBlock title into new…

ce0cb12

… metaOptions

refactor(theme-common, theme-classic): Use metaOptions for live

066ae85

refactor(theme-common, theme-live-codeblock): Use metaOptions for noI…

102fb9a

…nline

refactor(theme-common, theme-classic): Use metaOptions for showLineNu…

fd445fc

…mbers

test(theme-common): Update codeBlockUtils tests

f1ad7bb

refactor(theme-common): Do not fill invalid/missing options

b22a056

Danielku15 force-pushed the feature/codeblock-meta-2 branch from f8b3736 to dbb2dcc Compare March 28, 2025 17:18

test(theme-common): More tests for currently known options

7136e71

Danielku15 force-pushed the feature/codeblock-meta-2 branch from dbb2dcc to 7136e71 Compare March 29, 2025 13:02

slorber closed this Apr 4, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(theme-common, theme-classic, theme-live-codeblock): Parse `metastring` into `metaOptions` and use it across components #11019

refactor(theme-common, theme-classic, theme-live-codeblock): Parse `metastring` into `metaOptions` and use it across components #11019

Danielku15 commented Mar 22, 2025 •

edited

Loading

netlify bot commented Mar 22, 2025 •

edited

Loading

github-actions bot commented Mar 22, 2025 •

edited

Loading

slorber Mar 28, 2025

slorber Mar 28, 2025

Danielku15 Mar 28, 2025

slorber Mar 28, 2025

Danielku15 Mar 28, 2025

slorber Mar 28, 2025

Danielku15 Mar 28, 2025 •

edited

Loading

Check failure

Danielku15 Mar 28, 2025

slorber commented Apr 4, 2025

refactor(theme-common, theme-classic, theme-live-codeblock): Parse metastring into metaOptions and use it across components #11019

refactor(theme-common, theme-classic, theme-live-codeblock): Parse metastring into metaOptions and use it across components #11019

Conversation

Danielku15 commented Mar 22, 2025 • edited Loading

Pre-flight checklist

Motivation

Test Plan

Test links

Related issues/PRs

netlify bot commented Mar 22, 2025 • edited Loading

✅ [V2]

github-actions bot commented Mar 22, 2025 • edited Loading

⚡️ Lighthouse report for the deploy preview of this PR

slorber Mar 28, 2025

Choose a reason for hiding this comment

slorber Mar 28, 2025

Choose a reason for hiding this comment

Danielku15 Mar 28, 2025

Choose a reason for hiding this comment

slorber Mar 28, 2025

Choose a reason for hiding this comment

Danielku15 Mar 28, 2025

Choose a reason for hiding this comment

slorber Mar 28, 2025

Choose a reason for hiding this comment

Danielku15 Mar 28, 2025 • edited Loading

Choose a reason for hiding this comment

Check failure

Danielku15 Mar 28, 2025

Choose a reason for hiding this comment

slorber commented Apr 4, 2025

refactor(theme-common, theme-classic, theme-live-codeblock): Parse `metastring` into `metaOptions` and use it across components #11019

refactor(theme-common, theme-classic, theme-live-codeblock): Parse `metastring` into `metaOptions` and use it across components #11019

Danielku15 commented Mar 22, 2025 •

edited

Loading

netlify bot commented Mar 22, 2025 •

edited

Loading

github-actions bot commented Mar 22, 2025 •

edited

Loading

Danielku15 Mar 28, 2025 •

edited

Loading