Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion packages/docusaurus-theme-classic/src/theme-classic.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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;
}
Comment on lines +497 to +500
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TokenOutputProps props are directly applicable to spans

I'd prefer to have

type TokenOutputProps = {
    style?: StyleObj;
    className: string;
    children: string;
    [key: string]: unknown;
};

export interface Props extends TokenOutputProps {
    readonly meta?: CodeBlockMeta;
}

Eventually, we could introduce a React code block context to provide the meta to all the subtree. This makes it easier to reduce coupling between code block components, by avoiding passing global context through props (less likely to break on swizzle)

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I had this before but decided not to inherit but composite because:

  1. meta should not be applied to span. Hence you end up with something similar const {meta, rest} = props; ... (<span {...rest} />). (I noticed that CodeBlockToken has a bug not having <span {...props.output} /> like it should and <CodeBlockToken /> not receiving meta
  2. When swizzling you can clearly differenciate between the general token inputs (like meta) and what options should be applied to the element for the output.

Generally I'm fine with the change, just wanted to be sure we consider those aspects.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks awkward to me to have {...props.output}, and why we have to name a thing output in the first place. The component shouldn't be designed according to names chosen by a third-party library, it must make sense in isolation. Would you use the name "output" if you weren't using react-prism-renderer for example, and were simply designing a standalone code block token component?

If meta is accessible through context, there's no need to {meta, ...rest} because meta is not a prop.


export default function CodeBlockToken(props: Props): ReactNode;
}

declare module '@theme/CodeBlock/WordWrapButton' {
import type {ReactNode} from 'react';

Expand Down
18 changes: 9 additions & 9 deletions packages/docusaurus-theme-classic/src/theme/CodeBlock/Content/String.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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, {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't see why parseLines should parse the metastring.

Can't we provide the meta as input?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can be changed. The decision behind this was:

  • Keeping the existing "responsibilities" (parseLines being responsible for parsing the lines related to the codeblock).
  • Assuming we will at some point in future also parse options from metacomments inside the code (see RFC), it would be parseLines parsing additional data into meta.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • Keeping the existing "responsibilities" (parseLines being responsible for parsing the lines related to the codeblock).

Not sure to understand, this method's responsibility is not really parsing the metastring, but parsing lines magic comments.

  • Assuming we will at some point in future also parse options from metacomments inside the code (see RFC), it would be parseLines parsing additional data into meta.

I'm not sure about the "Metadata Magic Comments" feature.

Even if we eventually introduce this, we'll only do this later once everything is in a better shape, and your design should be researched/challenged. It's always possible to refactor again later once we are sure we want this feature, but for now please ignore it.

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 (
Expand Down Expand Up @@ -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}
/>
))}
Expand Down
3 changes: 2 additions & 1 deletion packages/docusaurus-theme-classic/src/theme/CodeBlock/Line/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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];
Expand Down Expand Up @@ -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 (
Expand Down
13 changes: 13 additions & 0 deletions packages/docusaurus-theme-classic/src/theme/CodeBlock/Token/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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} />;
}
5 changes: 5 additions & 0 deletions packages/docusaurus-theme-common/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,3 +144,8 @@ export {
ErrorBoundaryErrorMessageFallback,
ErrorCauseBoundary,
} from './utils/errorBoundaryUtils';

export {
type CodeBlockMeta,
type CodeMetaOptionValue,
} from './utils/codeBlockUtils';
2 changes: 1 addition & 1 deletion packages/docusaurus-theme-common/src/internal.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ export {ColorModeProvider} from './contexts/colorMode';
export {useAlternatePageUtils} from './utils/useAlternatePageUtils';

export {
parseCodeBlockTitle,
parseCodeBlockMeta,
parseLanguage,
parseLines,
getLineNumbersStart,
Expand Down
Loading
Loading