feat(theme-classic): code block showLineNumbers #7007

lex111 · 2022-03-25T21:34:41Z

Motivation

It should be possible to show line numbering in code blocks, although this is not a commonly used use case. I once saw a request for such a feature by one our user in some time ago, so believe we can provide it out of the box.
For example Gatsby's code block highlighting plugin has such option, and MkDocs Material originally has such feature.

Therefore code line numbering should not be superfluous, although its implementation is not easy as could be, since it is important to be able to control the color (via opacity) of any line number, which it makes especially more sense when the code lines are highlighted.

I specially used in the docs an example with a long code line to demonstrate that the position of a element with line numbers must be fixed with the proper background -- it's important thing.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

See docs for example.

https://deploy-preview-7007--docusaurus-2.netlify.app/docs/markdown-features/code-blocks/#code-line-numbering

Related PRs

…e-block-line-numbers

netlify · 2022-03-25T21:43:40Z

✅ [V2]

Name	Link
🔨 Latest commit	`5951f28`
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/624ff7429f62250009dfb235
😎 Deploy Preview	https://deploy-preview-7007--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-25T21:43:57Z

⚡️ 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-7007--docusaurus-2.netlify.app/

github-actions · 2022-03-25T21:47:10Z

Size Change: +632 B (0%)

Total Size: 806 kB

Filename	Size	Change
`website/build/assets/css/styles.********.css`	106 kB	+535 B (+1%)
`website/build/assets/js/main.********.js`	612 kB	+97 B (0%)

ℹ️ View Unchanged

Filename	Size
`website/.docusaurus/globalData.json`	49.9 kB
`website/build/index.html`	38.6 kB

_{compressed-size-action}

Josh-Cena · 2022-03-26T01:22:33Z

I do know that CSS-only solutions exist, though, like this:

.prism-code {
  counter-reset: line-number;
}

.prism-code .token-line::before {
  counter-increment: line-number;
  content: counter(line-number);
  margin-right: calc(var(--ifm-pre-padding) * 1.5);
  text-align: right;
  min-width: 1.5rem;
  display: inline-block;
  opacity: .3;
  position: sticky;
  left: var(--ifm-pre-padding);
}

Effect: https://www.hscmathematics.com/latex/figures/functions/

I also have another open PR about adding collapsible lines: #5783 But I think Sebastien likes to make people swizzle / use CSS

lex111 · 2022-03-26T06:39:12Z

The CSS-only solution is unfortunately not flexible, in which case there is no way to apply opacity only to text of line number, so you get something like this:

Also, a number color of highlighted line should be different from the default, which can be achieved again by introducing an additional empty element. At least I don't see any other easy way to do this.

I understand that it enable line numbering in code blocks is not often necessary, but it does not require much code to implement. As I showed, the CSS-only solution has a disadvantage with long lines, and just creates an inconvenience if line numbering is needed for a certain code block in a document.

Josh-Cena · 2022-03-26T06:41:52Z

I see. Yeah, I thought about the same.

slorber

That looks nice and also something I wanted to see added 👍

Agree that CSS is not good enough in this case and having something available by default seems reasonable

I personally like this design (line highlighting, line hovering etc...): https://blog.maximeheckel.com/posts/advanced-animation-patterns-with-framer-motion/

Wonder if it works for live codeblocks? We should probably be consistent and make this available in both live/static code blocks?

slorber · 2022-04-06T14:23:19Z

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

@@ -71,6 +71,10 @@ export function parseCodeBlockTitle(metastring?: string): string {
  return metastring?.match(codeBlockTitleRegex)?.groups!.title ?? '';
 }

+export function containsLineNumbers(metastring?: string): boolean {
+  return metastring?.includes('showLineNumbers') || false;


was thinking maybe we should make it possible to have it enabled by default, and disable on a case-by-case basis?

I do not see the need for this, in most cases it is not necessary.

Yes, I think opt-in is better than opt-out in most cases. It usually adds unnecessary noise, because unless you want to reference one line of code in the main text, you don't need numbering. Another option is to add a default-false theme config option that adds line numbers to all code blocks, but IMO we don't have a strong use-case

Another option is to add a default-false theme config option that adds line numbers to all code blocks, but IMO we don't have a strong use-case

That's what I was thinking about, but we can add later if requested 👍

slorber · 2022-04-06T14:30:03Z

website/docs/guides/markdown-features/markdown-features-code-blocks.mdx

+````md
+```jsx showLineNumbers
+function PageLayout(props) {
+  return <Layout title="Awesome Docusaurus page" description="Just one more awesome page on my Docusaurus site">;


this example is not ideal, maybe add line breaks + find a way to use line highlighting + line numbers in doc?

I deliberately made this example with long line of code to show how line numbering will be positioned when scrolling. About adding line highlighting alongside showLineNumbers, it's good idea.

I see thanks

What about making the doc example simpler (not scrolling) and adding all edge cases to a dogfood doc to make review easier? (+10 lines, highlighting, scrolling...)

lex111 · 2022-04-06T18:23:25Z

I personally like this design (line highlighting, line hovering etc...)

I decided to use a design like in editors like VS Code or JetBrains IDE. It seems reasonable to me, considering that the Prism color scheme can change. And it's just more familiar and not as eye-catching (I also mean that the line numbers should be less contrasted by color in comparison with color of code)

Wonder if it works for live codeblocks?

I'm not sure about this, in any case it is a completely different third-party component, perhaps somehow we can add line numbering there, but it is better to do it in the another PR.

Josh-Cena

…e-block-line-numbers

lex111 · 2022-04-07T19:18:25Z

Well spotted, as usual, initially I wanted to do with a minimum amount of code, but in the end (as always) it doesn't work like that, so the final implementation is not so simple, but it covers all possible the use cases (see https://deploy-preview-7007--docusaurus-2.netlify.app/tests/pages/code-block-tests#code-blocks-with-line-numbering-tests)

Josh-Cena · 2022-04-08T00:44:22Z

The right padding causes a weird selection highlight:

Probably worth fixing

…docusaurus into lex111/code-block-line-numbers

slorber

great 👍 LGTM thanks

lex111 added 2 commits March 25, 2022 21:47

feat(theme-classic): allow line numbering to code blocks

0de49c3

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

0799a67

…e-block-line-numbers

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

lex111 requested review from slorber and Josh-Cena as code owners March 25, 2022 21:34

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

Josh-Cena changed the title ~~feat(theme-classic): allow line numbering to code blocks~~ feat(theme-classic): code block showLineNumbers Mar 26, 2022

Josh-Cena mentioned this pull request Mar 28, 2022

Add documentation for CodeBlock to describe className prop #7034

Closed

2 tasks

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

slorber approved these changes Apr 6, 2022

View reviewed changes

Josh-Cena requested changes Apr 7, 2022

View reviewed changes

lex111 added 3 commits April 7, 2022 14:37

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

12286a5

…e-block-line-numbers

Fix long line numbering

af5f8e5

Improve docs

92a6539

Merge github.com:facebook/docusaurus into lex111/code-block-line-numbers

bd5a394

lex111 force-pushed the lex111/code-block-line-numbers branch from e00a86c to bd5a394 Compare April 7, 2022 19:18

Remove redundant example

1d153a4

lex111 added 2 commits April 8, 2022 11:49

Proper selection highlight of numbered code

868f436

Merge branch 'lex111/code-block-line-numbers' of github.com:facebook/…

5951f28

…docusaurus into lex111/code-block-line-numbers

Josh-Cena approved these changes Apr 9, 2022

View reviewed changes

slorber approved these changes Apr 13, 2022

View reviewed changes

slorber merged commit ee4c984 into main Apr 13, 2022

slorber deleted the lex111/code-block-line-numbers branch April 13, 2022 12:42

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

lex111 mentioned this pull request Apr 14, 2022

refactor: control base styling of code blocks via CSS vars #7172

Merged

encody mentioned this pull request May 3, 2022

Add css style to add line numbers NEAR-Edu/welcome-track#7

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(theme-classic): code block showLineNumbers #7007

feat(theme-classic): code block showLineNumbers #7007

lex111 commented Mar 25, 2022 •

edited by slorber

Loading

netlify bot commented Mar 25, 2022 •

edited

Loading

github-actions bot commented Mar 25, 2022 •

edited

Loading

github-actions bot commented Mar 25, 2022 •

edited

Loading

Josh-Cena commented Mar 26, 2022

lex111 commented Mar 26, 2022

Josh-Cena commented Mar 26, 2022

slorber left a comment

slorber Apr 6, 2022

lex111 Apr 6, 2022

Josh-Cena Apr 7, 2022 •

edited

Loading

slorber Apr 7, 2022

slorber Apr 6, 2022

lex111 Apr 6, 2022

slorber Apr 7, 2022

lex111 commented Apr 6, 2022

Josh-Cena left a comment

lex111 commented Apr 7, 2022 •

edited

Loading

Josh-Cena commented Apr 8, 2022

slorber left a comment

feat(theme-classic): code block showLineNumbers #7007

feat(theme-classic): code block showLineNumbers #7007

Conversation

lex111 commented Mar 25, 2022 • edited by slorber Loading

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

Related PRs

netlify bot commented Mar 25, 2022 • edited Loading

✅ [V2]

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

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

Josh-Cena commented Mar 26, 2022

lex111 commented Mar 26, 2022

Josh-Cena commented Mar 26, 2022

slorber left a comment

Choose a reason for hiding this comment

slorber Apr 6, 2022

Choose a reason for hiding this comment

lex111 Apr 6, 2022

Choose a reason for hiding this comment

Josh-Cena Apr 7, 2022 • edited Loading

Choose a reason for hiding this comment

slorber Apr 7, 2022

Choose a reason for hiding this comment

slorber Apr 6, 2022

Choose a reason for hiding this comment

lex111 Apr 6, 2022

Choose a reason for hiding this comment

slorber Apr 7, 2022

Choose a reason for hiding this comment

lex111 commented Apr 6, 2022

Josh-Cena left a comment

Choose a reason for hiding this comment

lex111 commented Apr 7, 2022 • edited Loading

Josh-Cena commented Apr 8, 2022

slorber left a comment

Choose a reason for hiding this comment

lex111 commented Mar 25, 2022 •

edited by slorber

Loading

netlify bot commented Mar 25, 2022 •

edited

Loading

github-actions bot commented Mar 25, 2022 •

edited

Loading

github-actions bot commented Mar 25, 2022 •

edited

Loading

Josh-Cena Apr 7, 2022 •

edited

Loading

lex111 commented Apr 7, 2022 •

edited

Loading