Skip to content

Code blocks: Support partial text highlighting #1478

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.

Sign up for GitHub

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

Merged
ang-zeyu merged 21 commits into from
Feb 27, 2021
Merged

Code blocks: Support partial text highlighting #1478

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
a8e297c
Develop partial text highlighting
ryoarmanda Feb 12, 2021
913f05e
Incorporate line slice syntax on line range processing
ryoarmanda Feb 12, 2021
70ff67d
Update codeblock documentations
ryoarmanda Feb 12, 2021
52c6513
Update codeblock docs example
ryoarmanda Feb 12, 2021
f08167d
Update tests
ryoarmanda Feb 12, 2021
f7f9b55
Merge branch 'master' into part-of-text-highlighting
ryoarmanda Feb 13, 2021
cd7c0ea
Address reviews
ryoarmanda Feb 14, 2021
761066c
Add more convenience syntax for partial text highlight
ryoarmanda Feb 14, 2021
e0ad241
Generalize parts to slices conversion to multiple components
ryoarmanda Feb 14, 2021
61bd569
Tidy up and fix mistakes
ryoarmanda Feb 14, 2021
ef72888
Update tests
ryoarmanda Feb 14, 2021
2499138
Update docs
ryoarmanda Feb 14, 2021
26e9d25
Update docs again
ryoarmanda Feb 14, 2021
94f8b9a
Merge branch 'master' into part-of-text-highlighting
ryoarmanda Feb 20, 2021
ce67bf9
Improve line part syntax to highlight multiple occurrences
ryoarmanda Feb 21, 2021
363fd1f
Implement word-variant line-slice syntax
ryoarmanda Feb 24, 2021
9e1d927
Move code block processing to new file
ryoarmanda Feb 24, 2021
2f13afa
Move unescape helper to markdown-it
ryoarmanda Feb 24, 2021
71fb389
Rework highlight rule processing flow
ryoarmanda Feb 26, 2021
7e19b93
Summarize highlight rule formats documentation in a table
ryoarmanda Feb 27, 2021
cd40d8d
Address docs and minor code reviews
ryoarmanda Feb 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 40 additions & 19 deletions docs/userGuide/syntax/code.mbdf
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,47 +58,68 @@ function add(a, b) {


##### Line highlighting
To highlight lines, add the attribute `highlight-lines` as shown below.

You can specify highlighting in many different ways, depending on how you want it to be. There are two main variants:

**Text-only highlighting**

To highlight only the text portion of the line, you can just use the line numbers as is.

For ranges of lines, join the two line numbers with a dash sign (`-`).

**Whole-line highlighting**

If you wish to highlight a full line (including whitespaces) or ranges of it, you can leverage MarkBind's own _line-slice_ syntax. Line-slices are in the form of `lineNumber[:]`, e.g. `2[:]`.

This variant's format is very similar to the previous, but instead use line-slices rather than line numbers.

For ranges, you only need to use line-slices on either ends.
You can add the `highlight-lines` attribute to add highlighting to your code block. Refer to the example code block
below for a visual demonstration of all the possible ways of highlighting a code block.

<include src="codeAndOutputCode.md" boilerplate >

@ang-zeyu ang-zeyu Feb 27, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's shift this up before the value of highlight-lines... so the user has a brief idea what the usage is like first :-)

@ang-zeyu ang-zeyu Feb 27, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

might have missed one ^ @ryoarmanda
disregard if it looks stranger

@ryoarmanda ryoarmanda Feb 27, 2021 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I did this already @ang-zeyu, I just reworded the value of highlight-lines... to the ones in line 85-86 of the file

Edit: strange it doesn't show up in the diffs, you can look for it on the preview site, it's already changed there. Maybe because I force-pushed as I rebased a fixup?

@ang-zeyu ang-zeyu Feb 27, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this

was suggesting the reverse - moving the example up (the <include> tag), so the user gets a brief overview of the entire syntax usage first before the details

@ryoarmanda ryoarmanda Feb 27, 2021

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ahh okay, will rebase the fix shortly

@ryoarmanda ryoarmanda Feb 27, 2021

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done, the change is reverted in the force push :)


<variable name="code">
```java {highlight-lines="1,3[:],6-8,10[:]-12"}
```java {highlight-lines="1[:],3['Inventory'],4['It\'s designed'],5,6[8:18],8[0::2],12[:]-14,16-18,20[12:]-22,24[1::]-26"}
import java.util.List;

// Inventory is a class that stores inventory items in a list.
// It's designed as a thin wrapper on the List interface.
public class Inventory {
private List<Item> items;

public int getItemCount(){
return items.size();
}

public bool isEmpty() {
return items.isEmpty();
}

//...
public Item getItem(idx: int) {
return items.get(idx);
}

public void addItem(item: Item) {
return items.add(item);
}

public void removeItem(item: Item) {
return items.remove(item);
}
}
```
</variable>
</include>

The value of `highlight-lines` is composed of *highlight rules*, separated by commas.
These rules dictate where and how MarkBind should highlight your code block.

You can specify the highlight rules in many different ways, each is detailed as follows:

Type | Format | Example
-----|--------|--------
**Full text highlight**<br>Highlights the entirety of the text portion of the line | The line numbers as-is (subject to the starting line number set in `start-from`). | `3`, `5`
**Substring highlight**<br>Highlights _all_ occurrences of a substring in the line | `lineNumber[part]`<br><br>_Limitations_: `part` must be wrapped in quotes. If `part` contains a quote, escape it with a backslash (`\`). | `3['Inventory']`,`4['It\'s designed']`
**Character-bounded highlight**<br>Highlights a specific range of characters in the line | `lineNumber[start:end]`, highlights from character position `start` up to (but not including) `end`.<br><br>Character positions start from `0` as the first non-whitespace character, upwards.<br><br>Omit either `start`/`end` to highlight from the start / up to the end, respectively. | `19[1:5]`,`30[10:]`,`35[:20]`
**Word-bounded highlight**<br>Highlights a specific range of words in the line | `lineNumber[start::end]`, highlights from word position `start` up to (but not including) `end`.<br><br>Word positions start from `0` as the first word (sequence of non-whitespace characters), upwards.<br><br>Omit either `start`/`end` to highlight from the start / up to the end, respectively. | `5[2::4]`,`9[1::]`,`11[::5]`
**Full line highlight**<br>Highlights the entirety of the line | `lineNumber[:]` | `7[:]`

Not only a single line, MarkBind is also capable of highlighting ranges of lines in various ways. In general, the syntax
for range highlighting consists of two single line highlight rules as listed above joined by a dash (`-`).

Type | Format | Example
-----|--------|--------
**Ranged full text highlight**<br>Highlights from the first non-whitespace character to the last non-whitespace character | `lineStart-lineEnd` | `2-4`
**Ranged full line highlight**<br>Like ranged full text highlight, but highlights the entirety of the lines | `lineStart[:]-lineEnd` or `lineStart-lineEnd[:]` | `1[:]-5`,`10-12[:]`
**Ranged character-bounded highlight**<br>Highlights the text portion of the lines within the range, but starts/ends at an arbitrary character | `lineStart[start:]-lineEnd` or `lineStart-lineEnd[:end]` | `3[2:]-7`, `4-9[:17]`
**Ranged word-bounded highlight**<br>Like ranged character-bounded highlight, but starts/ends at an arbitrary word | `lineStart[start::]-lineEnd` or `lineStart-lineEnd[::end]` | `16[1::]-20`,`22-24[::3]`

##### Heading
To add a heading, add the attribute `heading` with the heading text as the value, as shown below.

Expand Down
44 changes: 42 additions & 2 deletions packages/cli/test/functional/test_site/expected/testCodeBlocks.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -223,13 +223,53 @@ <h3 id="testing-site-nav"><span id="testing-site-nav" class="anchor"></span>Test
</span><span>19
</span><span>20
</span></code></pre>
<p>**<code class="hljs inline no-lang" v-pre>highlight-lines</code> attr with line-slice syntax of empty indices should highlight leading/trailing spaces</p>
<p><strong><code class="hljs inline no-lang" v-pre>highlight-lines</code> attr with empty (any variant) line-slice syntax should highlight leading/trailing spaces</strong></p>
<pre><code class="hljs xml" v-pre><span><span class="hljs-tag">&lt;<span class="hljs-name">foo</span>&gt;</span>
</span><span class="highlighted"> <span class="hljs-tag">&lt;<span class="hljs-name">bar</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name">bar</span>&gt;</span>
</span><span> <span class="hljs-tag">&lt;<span class="hljs-name">baz</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name">baz</span>&gt;</span>
</span><span class="highlighted"> <span class="hljs-tag">&lt;<span class="hljs-name">baz</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name">baz</span>&gt;</span>
</span><span class="highlighted"> <span class="hljs-tag">&lt;<span class="hljs-name">qux</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name">qux</span>&gt;</span>
</span><span class="highlighted"> <span class="hljs-tag">&lt;<span class="hljs-name">quux</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name">quux</span>&gt;</span>
</span><span><span class="hljs-tag">&lt;/<span class="hljs-name">foo</span>&gt;</span>
</span></code></pre>
<p><strong><code class="hljs inline no-lang" v-pre>highlight-lines</code> attr with full character-variant line-slice syntax should highlight only at specified range</strong></p>
<pre><code class="hljs xml" v-pre><span><span class="hljs-tag">&lt;<span class="hljs-name highlighted">foo</span>&gt;</span>
</span><span> <span class="hljs-tag">&lt;<span class="hljs-name">bar</span> <span class="hljs-attr highlighted">type</span><span class="highlighted">=</span><span class="hljs-string"><span><span class="highlighted">&quot;na</span>me&quot;</span></span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name">bar</span>&gt;</span>
</span><span> <span class="hljs-tag">&lt;<span class="hljs-name"><span>b<span class="highlighted">az</span></span></span><span class="highlighted"> </span><span class="hljs-attr highlighted">type</span><span class="highlighted">=</span><span class="hljs-string">&quot;name&quot;</span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name">baz</span>&gt;</span>
</span><span> <span class="highlighted"><span class="hljs-tag">&lt;<span class="hljs-name">qux</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name">qux</span>&gt;</span></span>
</span><span> <span class="highlighted"><span class="hljs-tag">&lt;<span class="hljs-name">quux</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name">quux</span>&gt;</span></span>
</span><span><span class="hljs-tag"><span>&lt;<span class="highlighted">/</span></span><span class="hljs-name"><span><span class="highlighted">fo</span>o</span></span>&gt;</span>
</span></code></pre>
<p><strong><code class="hljs inline no-lang" v-pre>highlight-lines</code> attr with partial character-variant line-slice syntax should default highlight to start/end of line</strong></p>
<pre><code class="hljs xml" v-pre><span><span class="hljs-tag">&lt;<span class="hljs-name highlighted">foo</span><span class="highlighted">&gt;</span></span>
</span><span> <span class="hljs-tag"><span class="highlighted">&lt;</span><span class="hljs-name highlighted">bar</span><span class="highlighted"> </span><span class="hljs-attr highlighted">type</span><span class="highlighted">=</span><span class="hljs-string"><span><span class="highlighted">&quot;na</span>me&quot;</span></span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name">bar</span>&gt;</span>
</span><span> <span class="hljs-tag">&lt;<span class="hljs-name"><span>b<span class="highlighted">az</span></span></span><span class="highlighted"> </span><span class="hljs-attr highlighted">type</span><span class="highlighted">=</span><span class="hljs-string highlighted">&quot;name&quot;</span><span class="highlighted">&gt;</span></span><span class="highlighted">goo</span><span class="hljs-tag highlighted">&lt;/<span class="hljs-name">baz</span>&gt;</span>
</span><span> <span class="highlighted"><span class="hljs-tag">&lt;<span class="hljs-name">qux</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name">qux</span>&gt;</span></span>
</span><span> <span class="highlighted"><span class="hljs-tag">&lt;<span class="hljs-name">quux</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name">quux</span>&gt;</span></span>
</span><span><span class="hljs-tag"><span class="highlighted">&lt;/</span><span class="hljs-name">foo</span>&gt;</span>
</span></code></pre>
<p><strong><code class="hljs inline no-lang" v-pre>highlight-lines</code> attr with line-part syntax should highlight only at specified substring</strong></p>
<pre><code class="hljs xml" v-pre><span><span class="hljs-tag">&lt;<span class="hljs-name">foo</span>&gt;</span>
</span><span> <span class="hljs-tag">&lt;<span class="hljs-name">bar</span> <span class="hljs-attr highlighted">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name">bar</span>&gt;</span>
</span><span> <span class="hljs-tag">&lt;<span class="hljs-name highlighted">baz</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span>goo<span class="hljs-tag">&lt;/<span class="hljs-name highlighted">baz</span>&gt;</span>
</span><span> <span class="hljs-tag">&lt;<span class="hljs-name">qux</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span><span class="highlighted">go,o</span><span class="hljs-tag highlighted">&lt;/<span class="hljs-name">qux</span>&gt;</span>
</span><span> <span class="hljs-tag">&lt;<span class="hljs-name">quux</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span><span class="highlighted">go&#x27;o</span><span class="hljs-tag">&lt;/<span class="hljs-name">quux</span>&gt;</span>
</span><span><span class="hljs-tag">&lt;/<span class="hljs-name">foo</span>&gt;</span>
</span></code></pre>
<p><strong><code class="hljs inline no-lang" v-pre>highlight-lines</code> attr with full word-variant line-slice syntax should highlight only at specified word ranges</strong></p>
<pre><code class="hljs xml" v-pre><span><span class="hljs-tag highlighted">&lt;<span class="hljs-name">foo</span>&gt;</span>
</span><span> <span class="hljs-tag">&lt;<span class="hljs-name">bar</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span> goo <span class="hljs-tag highlighted">&lt;/<span class="hljs-name">bar</span>&gt;</span>
</span><span> <span class="hljs-tag highlighted">&lt;<span class="hljs-name">baz</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span> goo <span class="hljs-tag">&lt;/<span class="hljs-name">baz</span>&gt;</span>
</span><span> <span class="hljs-tag">&lt;<span class="hljs-name">qux</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span><span> <span class="highlighted">goo </span></span><span class="hljs-tag highlighted">&lt;/<span class="hljs-name">qux</span>&gt;</span>
</span><span> <span class="hljs-tag">&lt;<span class="hljs-name">quux</span> <span class="hljs-attr highlighted">type</span><span class="highlighted">=</span><span class="hljs-string highlighted">&quot;name&quot;</span><span class="highlighted">&gt;</span></span><span><span class="highlighted"> goo</span> </span><span class="hljs-tag">&lt;/<span class="hljs-name">quux</span>&gt;</span>
</span><span><span class="hljs-tag">&lt;/<span class="hljs-name">foo</span>&gt;</span>
</span></code></pre>
<p><strong><code class="hljs inline no-lang" v-pre>highlight-lines</code> attr with partial word-variant line-slice syntax should default highlight to start/end of line</strong></p>
<pre><code class="hljs xml" v-pre><span><span class="hljs-tag highlighted">&lt;<span class="hljs-name">foo</span>&gt;</span>
</span><span> <span class="hljs-tag">&lt;<span class="hljs-name">bar</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span> goo <span class="hljs-tag highlighted">&lt;/<span class="hljs-name">bar</span>&gt;</span>
</span><span> <span class="hljs-tag highlighted">&lt;<span class="hljs-name">baz</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span> goo <span class="hljs-tag">&lt;/<span class="hljs-name">baz</span>&gt;</span>
</span><span> <span class="hljs-tag">&lt;<span class="hljs-name">qux</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span><span> <span class="highlighted">goo </span></span><span class="hljs-tag highlighted">&lt;/<span class="hljs-name">qux</span>&gt;</span>
</span><span> <span class="hljs-tag highlighted">&lt;<span class="hljs-name">quux</span> <span class="hljs-attr">type</span>=<span class="hljs-string">&quot;name&quot;</span>&gt;</span><span><span class="highlighted"> goo</span> </span><span class="hljs-tag">&lt;/<span class="hljs-name">quux</span>&gt;</span>
</span><span><span class="hljs-tag">&lt;/<span class="hljs-name">foo</span>&gt;</span>
</span></code></pre>
<p><strong>Should render correctly with heading</strong></p>
<div class="code-block">
Expand Down
54 changes: 52 additions & 2 deletions packages/cli/test/functional/test_site/testCodeBlocks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,8 +56,8 @@ Content in a fenced code block
20
```

**`highlight-lines` attr with line-slice syntax of empty indices should highlight leading/trailing spaces
```xml {highlight-lines="2[:],4[:]-5[:]"}
**`highlight-lines` attr with empty (any variant) line-slice syntax should highlight leading/trailing spaces**

@ang-zeyu ang-zeyu Feb 25, 2021

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's add in the edge cases (if they are) earlier once fixed as well

```xml {highlight-lines="2[:],3[::],4[:]-5[:]"}
<foo>
<bar type="name">goo</bar>
<baz type="name">goo</baz>
Expand All @@ -66,6 +66,56 @@ Content in a fenced code block
</foo>
```

**`highlight-lines` attr with full character-variant line-slice syntax should highlight only at specified range**
```xml {highlight-lines="1[1:4],2[5:13],3[2:10]-4,5-6[1:4]"}
<foo>
<bar type="name">goo</bar>
<baz type="name">goo</baz>
<qux type="name">goo</qux>
<quux type="name">goo</quux>
</foo>
```

**`highlight-lines` attr with partial character-variant line-slice syntax should default highlight to start/end of line**
```xml {highlight-lines="1[1:],2[:13],3[2:]-4,5-6[:2]"}
<foo>
<bar type="name">goo</bar>
<baz type="name">goo</baz>
<qux type="name">goo</qux>
<quux type="name">goo</quux>
</foo>
```

**`highlight-lines` attr with line-part syntax should highlight only at specified substring**
```xml {highlight-lines="1[''],2['type'],3['baz'],4['go,o</qux>'],5['go\'o']"}
<foo>
<bar type="name">goo</bar>
<baz type="name">goo</baz>
<qux type="name">go,o</qux>
<quux type="name">go'o</quux>
</foo>
```

**`highlight-lines` attr with full word-variant line-slice syntax should highlight only at specified word ranges**
```xml {highlight-lines="1[0::1],2[3::4],3[0::2],4[2::4],5[1::3]"}
<foo>
<bar type="name"> goo </bar>
<baz type="name"> goo </baz>
<qux type="name"> goo </qux>
<quux type="name"> goo </quux>
</foo>
```

**`highlight-lines` attr with partial word-variant line-slice syntax should default highlight to start/end of line**
```xml {highlight-lines="1[0::],2[3::],3[::2],4[2::],5[::3]"}
<foo>
<bar type="name"> goo </bar>
<baz type="name"> goo </baz>
<qux type="name"> goo </qux>
<quux type="name"> goo </quux>
</foo>
```

**Should render correctly with heading**

```{heading="A heading"}
Expand Down
4 changes: 4 additions & 0 deletions packages/core/src/html/NodeProcessor.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ const { processInclude, processPanelSrc } = require('./includePanelProcessor');
const { Context } = require('./Context');
const linkProcessor = require('./linkProcessor');
const { insertTemporaryStyles } = require('./tempStyleProcessor');
const { highlightCodeBlock } = require('./codeblockProcessor');

const md = require('../lib/markdown-it');
const utils = require('../utils');
Expand Down Expand Up @@ -746,6 +747,9 @@ class NodeProcessor {
postProcessNode(node) {
try {
switch (node.name) {
case 'pre':
highlightCodeBlock(node);
break;
case 'panel':
NodeProcessor._assignPanelId(node);
break;
Expand Down
Loading