Add information about line numbering and line highlighting into documentation

[talatkuyuk]

Initial checklist

• I read the support docs
• I read the contributing guide
• I agree to follow the code of conduct
• I searched issues and couldn’t find anything (or linked relevant results below)
• If applicable, I’ve added docs and tests

Description of changes

It is about for adding information about line numbering and line highlighting into documentation, which is done via rehype plugin rehype-highlight-code-lines. An example has been provided as well.

Fixes #29

[wooorm]

Hi again Talat, thanks for your patience, I was a bit busy. I took your take as inspiration and wrote a short example in the existing example section! Thank you.

Also: looks like the email you git commit with isn’t connected to your GitHub account; I think they describe how to add an email address here: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-email-preferences/setting-your-commit-email-address.

Or, perhaps, you accidentally added literal quotes locally in Git itself? 🤔

Finally, for your plugin:
your plugin supports a markdown syntax on how to highlight particular lines. That’s very useful!
But, these rehype plugins can also be used with plain HTML. So, I suggest to also support HTML attributes.
I’ve done something similar with rehype-twoslash recently, which accepts ```js twoslash but also class="language-js twoslash".

[talatkuyuk]

Also: looks like the email you git commit with isn’t connected to your GitHub account; Or, perhaps, you accidentally added literal quotes locally in Git itself? 🤔

You're right! I just realized that the commit author was set as “talatkuyuk” instead of talatkuyuk. Somehow, my keyboard used curly quotes while setting up Git locally, which ended up playing a joke on me. 😄 I was wondering why my commits and work weren’t showing up on the GitHub chart. Turns out, there was no connection due to incorrect local settings! :) Ohhh..

I corrected the commit name across all my projects and force-pushed the changes, rewriting the entire Git history—which took some time. I used the git filter-repo utility for the task.

Thank you warning me. 👍

[talatkuyuk]

Rehype plugins can also be used with plain HTML. So, I suggest to also support HTML attributes.

You suggested that I add support for highlighting/numbering code lines using HTML attributes as well. I got it, and will try to do it.

For clarification, rehype-highlight-code-lines currently supports markdown syntax something like:

```js {1,3} showLineNumbers
console.log("Highlight this line");
console.log("Don't highlight this");
console.log("Highlight this too");
```

And, your suggestion is that rehype-highlight-code-lines allow an equivalent in pure HTML as well, such as:

<pre><code class="language-js" data-highlight-lines="1,3" data-show-line-numbers>
console.log("Highlight this line");
console.log("Don't highlight this");
console.log("Highlight this too");
</code></pre>

[wooorm]

Awesome, cool! 👍

[talatkuyuk]

Hi @wooorm,

I've updated the rehype-highlight-code-lines. Now, it supports the directives in html class and attributes in <code> element. v.1.1.0.

<pre><code class="language-typescript show-line-numbers" data-highlight-lines="2-4">
// content of the code
</code></pre>

But, the problem I discovered is that the hast-util-raw (in order to use html in markdown) is removing code.data in HAST, this prevents to use code fences and code html fragments in the same markdown file. Is there any possibility to preserve code.data when use rehype-raw. I saw the related issue, but my question is that is there any viable solution to keep code.data on behalf of the highlight plugins?. According to my expertise, most of the highlight plugins depends on code.data.meta. I don't see any benefit of removing it.

I will open a PR for updating the example related with rehype-highlight-code-lines in rehype-highlight README.

[wooorm]

The data-highlight-lines you show is different data from the node.data stuff.
And that is indeed what I suggest: you can support node.data.
And you can support element.properties.dataStuff.
This is what I do for rehype-twoslash too:

https://github.com/rehypejs/rehype-twoslash/blob/19c933630ebb3abcce32e0dea123bb6bb2511e2b/lib/index.js#L110-L114

A user can then also themselves, before using rehype-raw, turn those element.data.meta values into element.properties.dataStuff:

https://github.com/mdx-js/mdx/blob/63f39cea9d48db8e2544b6f357d4dde5d3caafbc/website/mdx-loader.js#L318-L319

[talatkuyuk]

This is what I do for rehype-twoslash too:

https://github.com/ipikuka/rehype-highlight-code-lines/blob/20b176e6c3a531934b8755c0eb722a3b5f010c42/src/index.ts#L396

Exactly, now, rehype-highlight-code-lines supports both.

• code.data.meta,
• code.properties.metastring,

And it also supports

• code.properties.dataStuff,
• code.properties.classname

https://github.com/ipikuka/rehype-highlight-code-lines/blob/20b176e6c3a531934b8755c0eb722a3b5f010c42/src/index.ts#L416C6-L430C58

A user can then also themselves, before using rehype-raw, turn those element.data.meta values into element.properties.dataStuff

Something like that (before rehype-raw in plugin chain).

import type { Plugin } from "unified";
import type { Root } from "hast";
import { visit, type VisitorResult } from "unist-util-visit";

/**
 *
 * copy code.data.meta into code.properties.metastring
 *
 * use it before rehype-raw since it destroys the code.data.meta
 *
 */
const pluginCodeMeta: Plugin<void[], Root> = () => {
  return (tree: Root): undefined => {
    visit(tree, "element", function (code, index, parent): VisitorResult {
      if (!parent || index === undefined || code.tagName !== "code") {
        return;
      }

      if (parent.type !== "element" || parent.tagName !== "pre") {
        return;
      }

      code.properties.metastring = code.data?.meta;
    });
  };
};