Support line numbers for code blocks

[openorclose]

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [ ] Documentation update
• [ ] Bug fix
• [ ] New feature
• [x] Enhancement to an existing feature
• [ ] Other, please explain:

Partially fixes #473 (only adding support for line nos),

Fixes #1023

What is the rationale for this request?

What changes did you make? (Give an overview)

Small bugfix:

Our code fences (```) do not support markdown-it-attrs even though one of the examples there shows it should.

Turns out this is due to our overriding of the syntax highlighting.

We copied the second example from markdown-it, so that we could add our own hljs class to the <pre> tag, but this breaks markdown-it-attrs since the attrs there do not get added to our hardcoded pre tag.

So instead we provide our own renderer to render the attributes parsed by markdown-it-attrs.

Actual implementation

There is no way to directly use CSS and determine when line breaks happen, so we change highlightLines in markdown-it to split every \n and wrap a span around them.

Then, we use some css to insert the line numbers to it.

Line numbers will be shown by default, and authors can disable it by adding the class no-line-numbers.

Provide some example code that this change will affect:

```js
function f(n) {
  if (n < 1) {
    return 1;
  } else {
    return f(n - 1) + f(n - 2);
  }
}
f(10); // returns 12345;
```

Before and After:

If line numbers are not wanted:

```js {.no-line-numbers}
function f(n) {
  if (n < 1) {
    return 1;
  } else {
    return f(n - 1) + f(n - 2);
  }
}
f(10); // returns 12345;
```

Is there anything you'd like reviewers to focus on?

Check out the 2103 textbook here, where all code snippets have line numbers:
(the search on top doesn't work, it will bring you to the actual 2103 book site)
https://openorclose.github.io/se-book/

These pages have many code snippets:

• https://openorclose.github.io/se-book/codeQuality/
• https://openorclose.github.io/se-book/oop/
• https://openorclose.github.io/se-book/testing/
• https://openorclose.github.io/se-book/cppToJava/

Testing instructions:
Verify that <span>s get added to html of code fences, and manually check generated code fences for line numbers.

Proposed commit message: (wrap lines at 72 characters)

Add line numbers for code blocks

Let's wrap each line of a code block in a `<span>`,
and then add relevant css styles to display line numbers beside.

Line numbers will be displayed by default.

To turn off line numbers, add the class `no-line-numbers`
to a code block via markdown-it-attrs:

```js {.no-line-numbers}
const js = 1;
```

// TODO when design finalised

[damithc]

Nice. Can we make it the default? i.e., all fenced code blocks will have line numbers by default.

[openorclose]

Nice. Can we make it the default? i.e., all fenced code blocks will have line numbers by default.

Sure, then users can disable it similarly (or add any other classes they want) by doing {.no-line-numbers}?

[yamgent]

Sure, then users can disable it similarly (or add any other classes they want) by doing {.no-line-numbers}?

Yes please do provide the option to disable it.

[openorclose]

Ok changes made,

Now all code fences that specify a language will have numbered lines.

Add the class no-line-numbers to disable.

[alyip98]

Should this rule be changed to apply on .hljs instead? I doubt it will have an observable effect but it would be better practice.

[openorclose]

You mean pre.hljs instead?

[alyip98]

What do you think of supporting arbitrary starting line numbers? I could see some use cases where the author wants to show a short code snippet without showing the whole file.

[yamgent]

This PR is breaking the rendering of some code snippets, and also some scrollbars just appearing randomly:

[openorclose]

This PR is breaking the rendering of some code snippets, and also some scrollbars just appearing randomly:

When a language is not specified, the .hljs class is not applied by markdown it, which is probably why the old solution was used in the first place to add the .hljs class to code fences with no language. Bc

But reverting the change would break markdown-it-attrs for code fences.

[yamgent]

But reverting the change would break markdown-it-attrs for code fences.

Is it possible for MarkBind to add the class back in after all markdown syntax has been rendered (i.e. some post-rendering processing)?

[openorclose]

Is it possible for MarkBind to add the class back in after all markdown syntax has been rendered (i.e. some post-rendering processing)?

I made code highlighting a new renderer rule instead of using the highlight property from markdown-it, so it works fine now.

.

This allows us to manually render the attributes parsed from markdown-it-attrs.

What do you think of supporting arbitrary starting line numbers? I could see some use cases where the author wants to show a short code snippet without showing the whole file.

This would require a separate markdown plugin, as it is not possible (i.e. not nice) with pure css.
I would do this along with the rest of #473 by introducing some new syntax like markdown-it-attrs in a separate PR.

On a separate note, why do inline styles not work with markdown it attrs?

```js {data=123 style="counter-set:90;"}
function f(n) {
  if (n < 1) {
    return 1;
  } else {
    return f(n - 1) + f(n - 2);
  }
}
f(10); // returns 12345;
```

I tried doing this,

The inline style does get parsed and rendered in renderAttrs, but gets stripped out in the final html:

I tried it with **hi** {style = "color:red"} too and the the style doesn't work there too.

[damithc]

This page seems to be broken https://deploy-preview-991--markbind-master.netlify.com/userguide/reusingcontents

[openorclose]

This page seems to be broken https://deploy-preview-991--markbind-master.netlify.com/userguide/reusingcontents

Forgot to manually escape code blocks without language, Thanks!

[openorclose]

Ready for review!

[damithc]

Good work so far; looking forward to using this feature.
In some cases, there's a lot of space between the numbers and the code?

[openorclose]

Good work so far; looking forward to using this feature.
In some cases, there's a lot of space between the numbers and the code?

I set it to to the size of 3 digits, since that's probably enough for most purposes:

This is what it looks like if I set the width to 2 digits:

What it looks like now:

To solve the space issue when there is only one digit, I changed the text to align right instead:

[alyip98]

The class .hljs is applied to the <code> inside of <pre>

[openorclose]

Fixed! thanks

[openorclose]

Some parts of the documentation have line numbers, but we don't really want that because they are not code (e.g. https://deploy-preview-991--markbind-master.netlify.com/userguide/). Let's disable them.

Thanks! I've edited them, looked for instances of ``` and couldn't find other similar pages.

[openorclose]

Fixes #1017, too with the added

pre {
    white-space: pre-wrap;
}

suggested in that issue

Before hovering:

After hovering:

[yamgent]

There are some additional rendering problems in the documentation, can you please take a look at these:

(Both of these pictures are in userGuide/formattingContents.html, left side is this PR, right side is the correct version)

[openorclose]

There are some additional rendering problems in the documentation, can you please take a look at these:

(Both of these pictures are in userGuide/formattingContents.html, left side is this PR, right side is the correct version)

Thanks!

This is due to hljs's rendering into <span>s sometimes containing line breaks:

*****
-----

gets rendered as one single span, so we can't just split the lines after highlighting.

So I decided to split the lines, then perform highlighting instead.

This causes a minor discrepancy with blockquotes (the single > is not highlighted, but then the following >> line is not highlighted as well

Horizontal and vertical spaces are fixed

[damithc]

Works in production. Nice! 👍 Thanks @openorclose and reviewers. Let's push ahead and make our code blocks the best of class!