feat(theme-classic): toggle code wrap button #7036

lex111 · 2022-03-28T05:50:38Z

Motivation

Code blocks with long lines sometimes inconvenient to read, especially on mobile devices. But what if next to the copy code button, there was a button to toggle line wrapping? I mean that button would show up only when needed (there are long lines in any code block which cause horizontal scrolling).

I'm still not sure about the need for this feature, but decided to implement it to demonstrate it action.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

Code for testing:

```js
function PageLayout(props) {
  // highlight-next-line
  return <Layout title="My awesome Docusaurus page" description="Just one more awesome page on my Docusaurus ite">;
}
```

https://deploy-preview-7036--docusaurus-2.netlify.app/tests/pages/code-block-tests

Related PRs

netlify · 2022-03-28T05:58:37Z

✅ [V2]

Name	Link
🔨 Latest commit	`0464aa9`
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/6262a16fa0abae00094480d9
😎 Deploy Preview	https://deploy-preview-7036--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 settings.

github-actions · 2022-03-28T05:59:02Z

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	63
🟢 Accessibility	100
🟢 Best practices	92
🟢 SEO	100
🟢 PWA	90

Lighthouse ran on https://deploy-preview-7036--docusaurus-2.netlify.app/

github-actions · 2022-03-28T06:00:20Z

Size Change: +194 B (0%)

Total Size: 802 kB

Filename	Size	Change
`website/build/assets/css/styles.********.css`	107 kB	+194 B (0%)

ℹ️ View Unchanged

Filename	Size
`website/.docusaurus/globalData.json`	50 kB
`website/build/assets/js/main.********.js`	606 kB
`website/build/index.html`	38.8 kB

_{compressed-size-action}

Josh-Cena · 2022-03-28T07:01:04Z

I'm not sure about the value of this feature either 🤷‍♂️ Do we have examples of existing sites with this feature?

There's a Canny request for this: https://docusaurus.canny.io/feature-requests/p/toggle-line-wrap-in-code-blocks And I did vote for it long ago, but it doesn't seem to have any significant traction, and I also don't see huge value in having it OOTB

lex111 · 2022-03-28T17:19:27Z

This feature is more likely to be useful for mobiles users, because on small screens code blocks will usually be scrollable. So let's wait for feedback from @slorber then.
And no, I can't think of any docs sites that have this feature.

Dannyholt · 2022-03-28T23:32:06Z

I'd like to see this added as we include a lot of WordPress hook examples and so, wrapping the code would make this easier for a non-technical users and as @lex111 mentioned, would help on mobile devices. :)

Josh-Cena · 2022-03-29T10:17:46Z

I see. The mobile use-case makes a lot of sense.

packages/docusaurus-theme-classic/src/theme/CodeBlock/WordWrapButton/styles.module.css

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

…e-wrap

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

packages/docusaurus-theme-translations/locales/ru/theme-common.json

slorber

Looks interesting, willing to add this feature 👍

Some implementation details worth reworking

packages/docusaurus-theme-translations/locales/fr/theme-common.json

slorber · 2022-04-07T14:39:34Z

packages/docusaurus-theme-classic/src/theme/CodeBlock/styles.module.css

+.codeButton {
+  --docusaurus-code-button-size: 2rem;
+  position: absolute;
+  right: calc(var(--ifm-pre-padding) / 2);
+  top: calc(var(--ifm-pre-padding) / 2);
+  width: var(--docusaurus-code-button-size);
+  height: var(--docusaurus-code-button-size);
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  background: inherit;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: var(--ifm-global-radius);
+  transition: opacity 200ms ease-in-out;
+  opacity: 0;
+}


we should try to separate this CSS in 2 parts:

the "inner" of a code button (can be extracted and moved to a separate CodeButton component)

the rules that are responsible to position the button inside the parent component

slorber · 2022-04-07T14:42:55Z

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

+    setIsEnabled((value) => !value);
+
+    const codeElement = codeBlockRef.current!.querySelector('code');
+    codeElement?.classList.toggle(styles.codeWithWordWrap!);
+  }, [codeBlockRef]);
+  const updateCodeIsScrollable = useCallback(() => {
+    const {scrollWidth, clientWidth} = codeBlockRef.current!;
+    setIsCodeScrollable(scrollWidth > clientWidth);
+  }, [codeBlockRef]);
+  const title = translate({
+    id: 'theme.CodeBlock.wordWrapToggle',
+    message: 'Toggle word wrap',
+    description:
+      'The title attribute for toggle word wrapping button of code block lines',
+  });
+
+  useEffect(() => {
+    updateCodeIsScrollable();
+
+    window.addEventListener('resize', updateCodeIsScrollable);
+
+    return () => {
+      window.removeEventListener('resize', updateCodeIsScrollable);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  if (!isCodeScrollable) {
+    return null;
+  }


all this code is quite technical and shouldn't be there

The button should preferably always render a button, and users swizzling it should be able to change its display/icon without having to manage this technical code.

I don't think the button should either handle a ref of parent code block. It's the parent that should decide if the toggle button should be displayed, not the button itself.

I'd suggest moving this complexity to a custom hook in theme-common, and using the hook inside <CodeBlock> instead <WordWrapButton>

slorber · 2022-04-07T14:47:57Z

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

+            <WordWrapButton
+              className={styles.codeButton}
+              codeBlockRef={codeBlockRef}
+            />


What I have in mind:

Suggested change

<WordWrapButton

className={styles.codeButton}

codeBlockRef={codeBlockRef}

/>

{(wordWrap.enabled || wordWrap.codeScrollable) && (

<WordWrapButton

className={styles.codeButton}

onClick={() => wordWrap.toggle()}

/>

)}

slorber · 2022-04-07T14:51:39Z

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

+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, []);
+
+  if (!isCodeScrollable) {


Little issue:

mobile

enable word wrap

resize

Now isCodeScrollable = false and the button disappears => no way to turn word wrap off

slorber · 2022-04-07T14:55:13Z

packages/docusaurus-theme-classic/src/theme/CodeBlock/WordWrapButton/styles.module.css

+ */
+
+.wordWrapButton {
+  right: calc(


I'd like the button to not decide where it will be rendered: that's the responsibility of the parent

I don't like it either, I was thinking of grouping these buttons into one new div container, but it's not that easy because we would have to somehow get background of the current Prism color theme (need it for button background, not its container). Therefore inherit value won't work here, so maybe we dynamically set two new CSS vars, like as --prism-background and --prism-color? Will that be acceptable solution?

Maybe this works? usePrismTheme().plain.backgroundColor

I mean, in the case of button container, we need to set the style attribute for each button inside to set the proper background. I think it's kind of redundant overhead, which we can avoid by dynamically creating two CSS vars that also can re-use in other places where the style attribute is currently used.

@lex111 FWIW, Prism also inlines their styles, so it won't be too harmful

Just wouldn't want to overuse it, especially if there's a pretty appropriate alternative solution. Beside that, using inline styles would require creating one specific prop style for each button component, which can also be avoided.

Is this rule still necessary?

Looks to me it's not useful anymore => removing it and things keep working?

…e-wrap

….json Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>

lex111

Ready for re-review.

slorber

👍

Fixed a minor edge case in 5a14be5

Minor cleanups can probably be done, I think there's some unused CSS

Wonder if we could share more code between the 2 buttons, but that doesn't seem critical to merge

slorber · 2022-04-21T10:33:52Z

packages/docusaurus-theme-classic/src/theme/CodeBlock/WordWrapButton/styles.module.css

+ */
+
+.wordWrapButton {
+  right: calc(


Is this rule still necessary?

Looks to me it's not useful anymore => removing it and things keep working?

packages/docusaurus-theme-classic/src/theme/CodeBlock/Content/styles.module.css

slorber · 2022-04-21T10:35:32Z

packages/docusaurus-theme-classic/src/theme/CodeBlock/WordWrapButton/styles.module.css

+}
+
+.wordWrapButtonIcon {
+  width: 1.2rem;


maybe we want to use the same size for all buttongroup icons? and introduce anv env variable to customize?

It doesn't work that way, the proportions of both icons are different, so if we use the same sizing for them, the wordWrap button will look smaller than the copyButton icon:

we can keep it this way for now, but I guess the wordWrap svg could also be cropped somehow to take full space

packages/docusaurus-theme-classic/src/theme/CodeBlock/WordWrapButton/styles.module.css

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

…e-wrap

slorber

LGTM thanks 👍

Will do the minor change and merge

slorber · 2022-04-22T12:30:06Z

packages/docusaurus-theme-common/src/hooks/useCodeWordWrap.ts

+import {useState, useCallback, useEffect, useRef} from 'react';
+
+export function useCodeWordWrap(): {
+  readonly codeBlockRef: (node: HTMLPreElement | null) => void;


this is not needed to use a function here you can return the React ref and assign it directly (like it was before, but instead it's created in the custom hook instead of the component

alexfornuto · 2022-05-17T15:38:40Z

It looks like this was merged without being documented. Because it's not working in my testing, I'm looking for (and not finding) a way to disable this feature.

Josh-Cena · 2022-05-17T15:44:02Z

@alexfornuto This is not an opt-in feature and there's no option for this. If you want to disable this, you have to swizzle CodeBlock and remove the relevant code.

What's not working for you?

alexfornuto · 2022-05-18T16:30:26Z

@Josh-Cena thanks for the reply. Example preview here shows the following example, two code blocks, each in a tab:

<Tabs>

<TabItem value="yum" label="Yum">

```abnf title="/etc/yum.repos.d/pomerium-pomerium.repo"
[pomerium-pomerium]
name=pomerium-pomerium
baseurl=https://dl.cloudsmith.io/public/pomerium/pomerium/rpm/el/$releasever/$basearch
repo_gpgcheck=1
enabled=1
gpgkey=https://dl.cloudsmith.io/public/pomerium/pomerium/gpg.6E388440B94E1407.key
gpgcheck=1
sslverify=1
pkg_gpgcheck=1
```

</TabItem>
<TabItem value="deb" label="Deb">

```bash
curl -1sLf 'https://dl.cloudsmith.io/public/pomerium/pomerium/gpg.6E388440B94E1407.key' | apt-key add -
echo "deb https://dl.cloudsmith.io/public/pomerium/pomerium/deb/debian buster main" > /etc/apt/sources.list.d/pomerium-pomerium.list
```

</TabItem>
</Tabs>

While other code blocks on the linked page display and use the wrap button, these do not behave as expected:

In the first tab the button is present but not functioning.
In the second tab the button is not present, despite the code block overflowing.

This example is using 2.0.0-beta.20

Josh-Cena · 2022-05-18T16:36:18Z

That seems like a bug. Please open an issue.

magician11 · 2023-11-06T12:51:19Z

is there a way to toggle it on by default? I'm using it to show paragraphs of text..

Josh-Cena · 2023-11-07T01:42:32Z

@magician11 #7875 is the closest. If you think that won't satisfy your use case please submit a new issue instead of posting under an old PR.

feat(theme-classic): toggle code wrap button

f37f1b9

lex111 added the pr: new feature This PR adds a new API or behavior. label Mar 28, 2022

lex111 requested review from slorber and Josh-Cena as code owners March 28, 2022 05:50

facebook-github-bot added the CLA Signed Signed Facebook CLA label Mar 28, 2022

Josh-Cena reviewed Mar 29, 2022

View reviewed changes

packages/docusaurus-theme-classic/src/theme/CodeBlock/WordWrapButton/styles.module.css Show resolved Hide resolved

Josh-Cena reviewed Mar 29, 2022

View reviewed changes

packages/docusaurus-theme-classic/src/theme/CodeBlock/WordWrapButton/index.tsx Outdated Show resolved Hide resolved

Josh-Cena reviewed Mar 29, 2022

View reviewed changes

packages/docusaurus-theme-classic/src/theme/CodeBlock/WordWrapButton/index.tsx Outdated Show resolved Hide resolved

lex111 added 3 commits March 29, 2022 20:25

Merge branch 'main' of github.com:facebook/docusaurus into lex111/cod…

7d483b4

…e-wrap

Add resize listener

f6bae8b

Add support for i18n

dab2f96

Josh-Cena reviewed Mar 30, 2022

View reviewed changes

packages/docusaurus-theme-classic/src/theme/CodeBlock/WordWrapButton/index.tsx Outdated Show resolved Hide resolved

Josh-Cena added the status: awaiting review This PR is ready for review, will be merged after maintainers' approval label Mar 30, 2022

Josh-Cena reviewed Apr 7, 2022

View reviewed changes

packages/docusaurus-theme-translations/locales/ru/theme-common.json Show resolved Hide resolved

slorber requested changes Apr 7, 2022

View reviewed changes

lex111 added 2 commits April 15, 2022 17:34

Merge branch 'main' of github.com:facebook/docusaurus into lex111/cod…

6d57368

…e-wrap

Fixes

97e6922

lex111 force-pushed the lex111/code-wrap branch from ebb2d9e to 97e6922 Compare April 16, 2022 08:12

lex111 and others added 2 commits April 16, 2022 11:13

Update packages/docusaurus-theme-translations/locales/fr/theme-common…

82966a2

….json Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>

Revert code-block-tests.mdx

4b19c7a

lex111 commented Apr 20, 2022

View reviewed changes

codeWordWrap toggling can impact scroll => trigger update

5a14be5

slorber approved these changes Apr 21, 2022

View reviewed changes

lex111 added 3 commits April 22, 2022 12:45

Improvements after review

3b43394

Merge branch 'main' of github.com:facebook/docusaurus into lex111/cod…

579b8aa

…e-wrap

Remove duplicate code

e8d2841

slorber approved these changes Apr 22, 2022

View reviewed changes

return useRef() value directly

0464aa9

slorber merged commit 4e4aa6a into main Apr 22, 2022

slorber deleted the lex111/code-wrap branch April 22, 2022 12:50

Josh-Cena removed the status: awaiting review This PR is ready for review, will be merged after maintainers' approval label Apr 22, 2022

alexfornuto mentioned this pull request May 18, 2022

Code Block Wrapping Behavior is Inconsistent. #7449

Closed

dpang314 mentioned this pull request May 25, 2022

fix(theme-classic): inconsistent code block wrapping #7485

Merged

3 tasks

JPeer264 mentioned this pull request Aug 1, 2022

Global toggle code wrap button #7875

Open

2 tasks

NikolayS mentioned this pull request Jul 6, 2023

[Snyk] Security upgrade stylelint from 13.13.1 to 15.10.1 NikolayS/docusaurus#90

Open

Qdigital mentioned this pull request Jul 6, 2023

[Snyk] Security upgrade stylelint from 13.13.1 to 15.10.1 Qdigital/docusaurus#88

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(theme-classic): toggle code wrap button #7036

feat(theme-classic): toggle code wrap button #7036

lex111 commented Mar 28, 2022 •

edited by slorber

Loading

netlify bot commented Mar 28, 2022 •

edited

Loading

github-actions bot commented Mar 28, 2022 •

edited

Loading

github-actions bot commented Mar 28, 2022 •

edited

Loading

Josh-Cena commented Mar 28, 2022 •

edited

Loading

lex111 commented Mar 28, 2022 •

edited

Loading

Dannyholt commented Mar 28, 2022

Josh-Cena commented Mar 29, 2022

slorber left a comment

slorber Apr 7, 2022

slorber Apr 7, 2022

slorber Apr 7, 2022

slorber Apr 7, 2022

slorber Apr 7, 2022

lex111 Apr 7, 2022

slorber Apr 8, 2022

lex111 Apr 8, 2022

Josh-Cena Apr 8, 2022

lex111 Apr 8, 2022

slorber Apr 21, 2022

lex111 left a comment

slorber left a comment •

edited

Loading

slorber Apr 21, 2022

slorber Apr 21, 2022

lex111 Apr 22, 2022

slorber Apr 22, 2022

slorber left a comment

slorber Apr 22, 2022

alexfornuto commented May 17, 2022

Josh-Cena commented May 17, 2022

alexfornuto commented May 18, 2022

Josh-Cena commented May 18, 2022

magician11 commented Nov 6, 2023

Josh-Cena commented Nov 7, 2023

feat(theme-classic): toggle code wrap button #7036

feat(theme-classic): toggle code wrap button #7036

Conversation

lex111 commented Mar 28, 2022 • edited by slorber Loading

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

Related PRs

netlify bot commented Mar 28, 2022 • edited Loading

✅ [V2]

github-actions bot commented Mar 28, 2022 • edited Loading

github-actions bot commented Mar 28, 2022 • edited Loading

Josh-Cena commented Mar 28, 2022 • edited Loading

lex111 commented Mar 28, 2022 • edited Loading

Dannyholt commented Mar 28, 2022

Josh-Cena commented Mar 29, 2022

slorber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lex111 left a comment

Choose a reason for hiding this comment

slorber left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

alexfornuto commented May 17, 2022

Josh-Cena commented May 17, 2022

alexfornuto commented May 18, 2022

Josh-Cena commented May 18, 2022

magician11 commented Nov 6, 2023

Josh-Cena commented Nov 7, 2023

lex111 commented Mar 28, 2022 •

edited by slorber

Loading

netlify bot commented Mar 28, 2022 •

edited

Loading

github-actions bot commented Mar 28, 2022 •

edited

Loading

github-actions bot commented Mar 28, 2022 •

edited

Loading

Josh-Cena commented Mar 28, 2022 •

edited

Loading

lex111 commented Mar 28, 2022 •

edited

Loading

slorber left a comment •

edited

Loading