Global toggle code wrap button

[JPeer264]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

Code wrap buttons have been implemented: #7036

The thing is that it is a little cumbersome if this needs to be done on each codeblock individually. This proposal is that this setting will be stored globally to set it to the users needs.

Self-service

• I'd be willing to do some initial work on this proposal myself.

[Josh-Cena]

We probably won't add a button (otherwise we need a "user control panel", which may not be a totally bad idea, like how MUI is doing it). But a global option seems worthwhile.

Why would you want to wrap the code? I've almost never wanted to wrap it.

[JPeer264]

Oh I am sorry. It seems this went sideways. What I meant is when the user toggles one it should toggle all others too (to be clear, I am also not a big fan of wrapping it - but some of our customers are now using the feature as it got shipped with docusaurus).

Basically only this line would be touched: https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-theme-common/src/hooks/useCodeWordWrap.ts#L61

E.g.:

- const [isEnabled, setIsEnabled] = useState(false);
+ const [isEnabled, setIsEnabled] = useLocalstorageState(false);

[Josh-Cena]

Oh, I see your point. Would you be happy with a theme option that syncs the wrap state between all code blocks?

[JPeer264]

Of course that would be ideal.

[slorber]

Others looking for a similar feature:

@jaredcbaum in #5468 (comment)

@jgoux in #7769

Please help us decide what should be done so that all of you are satisfied ;)

[JPeer264]

I would propose a new theme configuration. I think with these everything should be covered:

{
  codeBlockOptions: {
    // this identifies if the code block should be wrapped or not on the first page load 
    defaultAppearance: 'default' | 'wrapped'; // default: 'default'
    // if the wrap state should be stored globally or not
    enableWrapSync: boolean; // default: false
    // enables or disables the visual representation of the code wrap
    showWrap: boolean; // default: true
  };
}

[jaredcbaum]

{
    codeBlock: {
        // Option to show copy button
        showCopy: boolean; // default true

        // Option to show wrap button
        showWrap: boolean; // default true

        // Option to control default wrapping
        defaultWrap: boolean; // default false;
    }
}

IMHO this would be an ideal config setup for code blocks. Since these options would be in docusaurus.config.js, it can be assumed that these options are global. They could be overridden on a per instance basis by passing options to the CodeBlock component or a per page basis with a frontmatter value.

[JPeer264]

I like that! The only thing I miss is the localStorage/global sync (which was the origin of this issue).

[paulboocock]

I noticed in #7769 it was suggested that this could be enabled/forced for a single code block. I have the odd code block where it makes sense to have it forced on, or at least enabled by default.

So this syntax (or similar) would be great for me:

    ```bash wordWrap=true
     ...
    ```

Example: https://docs.snowplow.io/docs/collecting-data/collecting-from-own-applications/javascript-trackers/javascript-tracker/javascript-tracker-v3/tracker-setup/loading/

I could also add some linebreaks 🤷

However, most snippets are far better with word wrap disabled, so I wouldn't really want to change the default for the whole site, or to even remember it page by page.