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.

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

Global toggle code wrap button #7875

Open
2 tasks done
JPeer264 opened this issue Aug 1, 2022 · 21 comments · May be fixed by #9349
Open
2 tasks done

Global toggle code wrap button #7875

JPeer264 opened this issue Aug 1, 2022 · 21 comments · May be fixed by #9349
Labels
apprentice Issues that are good candidates to be handled by a Docusaurus apprentice / trainee feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future.

Comments

@JPeer264
Copy link
Contributor

JPeer264 commented Aug 1, 2022

Have you 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.
@JPeer264 JPeer264 added proposal This issue is a proposal, usually non-trivial change status: needs triage This issue has not been triaged by maintainers labels Aug 1, 2022
@Josh-Cena Josh-Cena added feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future. and removed proposal This issue is a proposal, usually non-trivial change status: needs triage This issue has not been triaged by maintainers labels Aug 1, 2022
@Josh-Cena
Copy link
Collaborator

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
Copy link
Contributor Author

JPeer264 commented Aug 1, 2022

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
Copy link
Collaborator

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

@JPeer264
Copy link
Contributor Author

JPeer264 commented Aug 1, 2022

Of course that would be ideal.

@slorber
Copy link
Collaborator

slorber commented Aug 9, 2022

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
Copy link
Contributor Author

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
Copy link

{
    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
Copy link
Contributor Author

JPeer264 commented Aug 29, 2022

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

@paulboocock
Copy link

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.

@gtnardy

This comment was marked as spam.

@khanh96le

This comment was marked as spam.

@sandys

This comment was marked as spam.

@ivancheban

This comment was marked as spam.

@1dealwaves

This comment was marked as spam.

@tarakta

This comment was marked as spam.

@lathropcat

This comment was marked as spam.

@RoksanaSkrzycka

This comment was marked as spam.

@slorber slorber added the apprentice Issues that are good candidates to be handled by a Docusaurus apprentice / trainee label Sep 25, 2023
@OzakIOne OzakIOne linked a pull request Sep 27, 2023 that will close this issue
@slorber
Copy link
Collaborator

slorber commented Sep 28, 2023

We started working on this in #9349, and a few questions arise because there are orthogonal needs

  • Should we always sync and persist in localStorage at the same time, or are these different features? IE could we sync the setting between code blocks without persisting the last choice, and vice versa?
  • Is sync/persistence opt-in or always enabled?
  • Should sync and/or persistence be enabled on a case-by-case basis, similar to how tabs work?
  • Do we need both a global site setting, and a code block meta-string param
  • If a global and/or meta string value is provided, and a localStorage value exist, what should be the value we use? We have 3 sources available to provide that value and need to figure a rule here.

As you can see, there are still design elements to discuss.


On the technical side, there are also important UX details to consider:

  • We need to ensure there's no layout shifts due to the sync when we click on the code wrap button (similar case to tabs we had in the past: the button position shifts and does not stay under user cursor)
  • We need to ensure a good React hydration experience. We don't want code blocks to initially appear with scrollbars and then shift to wrapping, producing layout shifts

@LVCarnevalli
Copy link

Hi everyone, do we have any updates on this 'wordWrap' feature?

@benjie
Copy link

benjie commented Dec 19, 2024

As a workaround, I wrap the code block in a div with a custom class:

<div className="wrapcode">

```
Error [ERR_REQUIRE_ESM]: Must use import to load ES Module: /path/to/graphile.config.ts
require() of ES modules is not supported.
require() of /path/to/graphile.config.ts from /path/to/node_modules/graphile-config/dist/loadConfig.js is an ES module file as it is a .ts file whose nearest parent package.json contains "type": "module" which defines all .ts files in that package scope as ES modules.
Instead change the requiring code to use import(), or remove "type": "module" from /path/to/package.json.
```

</div>

and added the wrapcode class to my src/css/custom.css:

.wrapcode code {
  white-space: pre-wrap;
}

benjie added a commit to jcgsville/crystal that referenced this issue Dec 19, 2024
benjie added a commit to jcgsville/crystal that referenced this issue Dec 19, 2024
@ivancheban
Copy link

I see that now Docusaurus code blocks have this code wrapping feature out-of-the-box: there's a Toggle word wrap button in the code blocks with long lines of code. Please close this issue.
image

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
apprentice Issues that are good candidates to be handled by a Docusaurus apprentice / trainee feature This is not a bug or issue with Docusausus, per se. It is a feature request for the future.
Projects
None yet
Development

Successfully merging a pull request may close this issue.