Skip to content

Commit 65d5f04

Browse files
talatkuyuktalatkuyuk
committed
updated README.md including the new directives for HTML classes and attributes
1 parent 56b05af commit 65d5f04

File tree

1 file changed

+110
-44
lines changed

1 file changed

+110
-44
lines changed

‎README.md

Lines changed: 110 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -100,26 +100,26 @@ async function main() {
100100
}
101101
```
102102

103-
Now, running `node example.js` you will see that each line of code is wrapped in a `div`, which has appropriate class names (`code-line`, `numbered-code-line`, `highlighted-code-line`) and line numbering attribute `data-line-number`.
103+
Now, running `node example.js` you will see that each line of code is wrapped in a `span`, which has appropriate class names (`code-line`, `numbered-code-line`, `highlighted-code-line`) and line numbering attribute `data-line-number`.
104104

105105
```html
106106
<pre>
107107
<code class="hljs language-javascript">
108-
<div class="code-line numbered-code-line" data-line-number="1">
108+
<span class="code-line numbered-code-line" data-line-number="1">
109109
<span class="hljs-keyword">let</span> a1;
110-
</div>
111-
<div
110+
</span>
111+
<span
112112
class="code-line numbered-code-line highlighted-code-line" data-line-number="2">
113113
<span class="hljs-keyword">let</span> a2;
114-
</div>
115-
<div class="code-line numbered-code-line" data-line-number="3">
114+
</span>
115+
<span class="code-line numbered-code-line" data-line-number="3">
116116
<span class="hljs-keyword">let</span> a3;
117-
</div>
117+
</span>
118118
</code>
119119
</pre>
120120
```
121121

122-
Without `rehype-highlight-code-lines`, the lines of code wouldn't be in a `div`.
122+
Without `rehype-highlight-code-lines`, the lines of code wouldn't be in a `span`.
123123

124124
```html
125125
<pre>
@@ -133,6 +133,92 @@ Without `rehype-highlight-code-lines`, the lines of code wouldn't be in a `div`.
133133

134134
***Note:** `hljs` prefix comes from `rehype-highlight`*.
135135

136+
## Usage in HTML attributes
137+
138+
**`rehype-highlight-code-lines`** runs on `<code>` elements with directives like `showLineNumbers` and range number in curly braces like `{2-4, 8}`. That directives can be passed as a word in markdown (` ```ts showLineNumbers {2-4, 8} `) or as a class and attribute in HTML (`<code class="language-ts show-line-numbers" data-highlight-lines="2-4, 8">`).
139+
140+
The inverse occurs when the option `showLineNumbers` is true. All `<code>` are processed and numbered. Then (` ```ts noLineNumbers `), or as a class (`<code class="language-ts no-line-numbers">`) can be used to prevent processing.
141+
142+
**The class directives can be with dash or without, or camel cased.**
143+
144+
See some example usage as HTML class and attributes *(only opening `<code>` tags are provided, the rest is omitted.)*:
145+
```html
146+
<code class="language-typescript show-line-numbers">
147+
<code class="language-typescript showlinenumbers">
148+
<code class="language-typescript showLineNumbers">
149+
150+
<code class="language-typescript show-line-numbers" data-highlight-lines="2-4">
151+
<code class="language-typescript show-line-numbers" data-start-numbering="11">
152+
<code class="language-typescript show-line-numbers" data-start-numbering="11" data-highlight-lines="2-4">
153+
154+
<code class="language-typescript no-line-numbers">
155+
<code class="language-typescript nolinenumbers">
156+
<code class="language-typescript noLineNumbers">
157+
<code class="language-typescript no-line-numbers" data-highlight-lines="2-4">
158+
159+
<code class="no-line-numbers">
160+
<code class="show-line-numbers">
161+
<code class="show-line-numbers" data-highlight-lines="2-4">
162+
<code data-highlight-lines="2-4">
163+
<code data-start-numbering="11">
164+
```
165+
166+
Say we have the following HTML fragment in a `example.md`:
167+
168+
```markdown
169+
<pre><code class="language-javascript show-line-numbers" data-highlight-lines="2">
170+
let a1;
171+
let a2;
172+
let a3;
173+
</code></pre>
174+
```
175+
176+
I assume you use `rehype-highlight` for code highlighting. Our module, `example.js`, looks as follows:
177+
178+
```javascript
179+
import { read } from "to-vfile";
180+
import remarkParse from "remark-parse";
181+
import remarkRehype from "remark-rehype";
182+
import rehypeRaw from "rehype-raw";
183+
import rehypeHighlight from "rehype-highlight";
184+
import rehypeHighlightLines from "rehype-highlight-code-lines";
185+
import rehypeStringify from "rehype-stringify";
186+
187+
main();
188+
189+
async function main() {
190+
const file = await unified()
191+
.use(remarkParse)
192+
.use(remarkRehype, { allowDangerousHtml: true })
193+
.use(rehypeRaw)
194+
.use(rehypeHighlight)
195+
.use(rehypeHighlightLines)
196+
.use(rehypeStringify)
197+
.process(await read("example.md"));
198+
199+
console.log(String(file));
200+
}
201+
```
202+
203+
Now, running `node example.js` you will see that each line of code is wrapped in a `span`, which has appropriate class names (`code-line`, `numbered-code-line`, `highlighted-code-line`) and line numbering attribute `data-line-number`.
204+
205+
```html
206+
<pre>
207+
<code class="hljs language-javascript">
208+
<span class="code-line numbered-code-line" data-line-number="1">
209+
<span class="hljs-keyword">let</span> a1;
210+
</span>
211+
<span
212+
class="code-line numbered-code-line highlighted-code-line" data-line-number="2">
213+
<span class="hljs-keyword">let</span> a2;
214+
</span>
215+
<span class="code-line numbered-code-line" data-line-number="3">
216+
<span class="hljs-keyword">let</span> a3;
217+
</span>
218+
</code>
219+
</pre>
220+
```
221+
136222
## Options
137223

138224
All options are **optional** and have **default values**.
@@ -141,7 +227,6 @@ All options are **optional** and have **default values**.
141227
type HighlightLinesOptions = {
142228
showLineNumbers?: boolean; // default is "false"
143229
lineContainerTagName?: "span" | "div"; // deprecated, always span
144-
trimBlankLines?: boolean; // default is "false"
145230
};
146231

147232
use(rehypeHighlightLines, HighlightLinesOptions);
@@ -159,22 +244,36 @@ use(rehypeHighlightLines, {
159244
});
160245
```
161246

162-
Now, all code blocks will become numbered. If you want to exclude a specific code block not to be numbered, use `noLineNumbers`.
247+
Now, all code blocks will become numbered.
248+
249+
If you want to exclude a specific code block not to be numbered, use `noLineNumbers`.
163250

164251
**\`\`\`[language] noLineNumbers {2}**
165252

166253
**\`\`\`[language] noLineNumbers**
167254

168255
**\`\`\`noLineNumbers**
169256

170-
Sometimes you may want to start the line numbering from a specific number. In that cases, use `showLineNumbers=[number]` in code blocks. For example, below, the code block's line numbering will start from number `8`.
257+
If you want to exclude a specific code block not to be numbered in HTML fragment (in `<pre>`) use `no-line-numbers` class. In that case, the directive could be with dash, or without, or camel cased.
258+
259+
**`<code class="language-ts no-line-numbers">`**
260+
261+
**`<code class="language-ts nolinenumbers">`**
262+
263+
**`<code class="language-ts noLineNumbers">`**
264+
265+
Sometimes you may want to start the line numbering from a specific number. In that cases, use `showLineNumbers=[number]` in code blocks. For example, below, the code block's line numbering will start from number `8`.
171266

172267
**\`\`\`[language] {2} showLineNumbers=8**
173268

174269
**\`\`\`[language] showLineNumbers=8**
175270

176271
**\`\`\`showLineNumbers=8**
177272

273+
If you want to start the line numbering from a specific number in HTML fragment (in `<pre>`) use `data-start-numbering` attribute.
274+
275+
**`<code class="..." data-start-numbering="8">`**
276+
178277
#### `lineContainerTagName` (Deprecated)
179278

180279
**It is marked as `@deprecated` and will be removed in the next versions.**
@@ -189,39 +288,6 @@ use(rehypeHighlightLines, {
189288
});
190289
```
191290

192-
#### `trimBlankLines`
193-
194-
It is a **boolean** option. It is designed to delete one blank/empty line at the beginning and one at the end of the code block, if happened due to html parsing `<pre><code /></pre>`.
195-
196-
By default, it is `false`.
197-
198-
Let's assume you want to highlight `pre`, and `code` element in markdown (not code fence).
199-
200-
```markdown
201-
Here is markdown content
202-
203-
<pre><code class="language-javascript">
204-
console.log("rehype-highlight-code-lines");
205-
</code></pre>
206-
```
207-
208-
For above markdown, the parsed result (for example via `rehype-parse` and `rehype-stringfy`) is going to contain empty/blank code lines due to nature of `pre` preserving whitespaces. In order to prevent having unintentionally blank lines, use the option `trimBlankLines`.
209-
210-
```javascript
211-
use(rehypeHighlightLines, {
212-
trimBlankLines: true,
213-
});
214-
```
215-
216-
Actually, the trimming could have been the default behaviour. However, some developers may intentionally include empty lines at the beginning and at the end in code fences for specific reasons and may want to preserve them.
217-
````markdown
218-
```javascript
219-
220-
console.log("rehype-highlight-code-lines");
221-
222-
```
223-
````
224-
225291
### Examples:
226292

227293
```typescript

0 commit comments

Comments
 (0)