example.qmd

---
title: "Code Line Highlight in html"
author: "Shafayet Khan Shafee"
date: "01-06-2023"
date-modified: last-modified
format: html
code-tools: true
toc: true
filters:
  - quarto
  - line-highlight
embed-resources: true
---

> Note: View the source code of this document by clicking `</> Code` on top-right corner.

## Highlighting Source Line Numbers

#### Example 01

Suppose we want to highlight the second line of the following code chunk, to do that, we simply use, `source-line-numbers: "2"`. Therefore,


```{r}
#| source-line-numbers: "2"
iris |> 
  head(5)
```

#### Example 02 (with source code line number)

Also, having the source code line numbered in such case would be helpful. We can do that by using source class `numberLines` (i.e. `#| class-source: "numberLines"`).

Here we have highlighted line number 2 and 6 to 7 and have also added line numbers at the left side using `numberLines` source-class.

```{r}
#| message: false
#| warning: false
#| class-source: "numberLines"
#| source-line-numbers: "2,6-7"

# library call
library(dplyr)

# code
iris |> 
  group_by(Species) |> 
  summarize(mean(Sepal.Length))
```


## Highlighting on markdown formatted codeblocks

Highlighting will also works on syntactically formatted markdown code blocks (non-executable)(e.g. `{.r}`, `{.python}`, `{.julia}` etc)

Use `source-line-numbers` as code-block attributes (i.e. \<attribute-name\>=\<value\>),

````{.r}
```{.r source-line-numbers="1,4"}
library(dplyr)

iris |> 
  group_by(Species) |> 
  summarize(mean(Sepal.Length))
```
````

Therefore, the above code block is rendered as,

```{.r source-line-numbers="1,4"}
library(dplyr)

iris |> 
  group_by(Species) |> 
  summarize(mean(Sepal.Length))
```

To get line numbers, use the `.numberLines` class additionally on the code-block,

````{.python}
```{.python source-line-numbers="3-4" .numberLines}
print("Hello world")

for name in ["Sam", "Jake"]:
    print(f"Hello {name}!")
```
````

which is then rendered as,

```{.python source-line-numbers="3-4" .numberLines}
print("Hello world")

for name in ["Sam", "Jake"]:
    print(f"Hello {name}!")
```


And you can use line-highlighting for code blocks of many different languages (languages for which pandoc supports syntax highlighting. See the list by running `pandoc --list-highlight-languages` if you have pandoc installed.)

````{.julia}
```{.julia .numberLines source-line-numbers="2-4"}
for i = 1:100
    str = i % 3 == 0 ? "Fizz" : ""
    str *= i % 5 == 0 ? "Buzz" : ""
    if isempty(str)
        str = i
    end
    println(str)
end
```
````

```{.julia .numberLines source-line-numbers="2-4"}
for i = 1:100
    str = i % 3 == 0 ? "Fizz" : ""
    str *= i % 5 == 0 ? "Buzz" : ""
    if isempty(str)
        str = i
    end
    println(str)
end
```

But of course, line highlighting also works on code blocks without language class name, but you will not get the syntax highlighting,

````{.julia}
```{.numberLines source-line-numbers="2-4"}
for i = 1:100
    str = i % 3 == 0 ? "Fizz" : ""
    str *= i % 5 == 0 ? "Buzz" : ""
    if isempty(str)
        str = i
    end
    println(str)
end
```
````

```{.numberLines source-line-numbers="2-4"}
for i = 1:100
    str = i % 3 == 0 ? "Fizz" : ""
    str *= i % 5 == 0 ? "Buzz" : ""
    if isempty(str)
        str = i
    end
    println(str)
end
```


## Using Highlight Marker instead of line numbers (Added in Version 1.2.0)

It is also possible to mark a line to be highlighted in the code chunk using the highlight directive  `#<<`. Note the syntax for the highlight directive, it starts with `#` (which is the commenting character for `r`, `python` and `julia` code chunk), followed by two `<` sign.

```{r}
iris |> #<<
  head(5) 
```

And if both the `source-line-numbers` chunk option and highlight directive is used in a code chunk, only the lines with highlight-directive `#<<` will be highlighted and `source-line-numbers` will not have any effect.

```{r}
#| source-line-numbers: "2"
iris |> #<<
  head(5)
```

**Now `#<<` will work as a valid highlight directive only for `r`, `python`, `julia` code chunk, since `#` is a commenting character in these languages.** But what if we want to highlight line in `mermaid` or `dot` code chunk. For that, `#<<` will not work and syntax error will be issued. Instead, we need to use these language specific commenting characters.

But this extension uses `#<<` as a highlight directive by default. To use different syntax for highlight directive for a code chunk, use chunk option `ht-pattern` to specify the highlight directive to be used for that code chunk, where the syntax should be `<language-specific-commenting-character><<`. 

Therefore, for `mermaid` cell, `ht-pattern` should be `%%<<` and for `dot` cell, `ht-pattern` should be `//<<`. Then use these to mark a code line to be highlighted.

```{mermaid}
%%| echo: true
%%| ht-pattern: "%%<<"
flowchart LR
  A[Hard edge] --> B(Round edge)
  B --> C{Decision}
  C --> D[Result one] %%<<
  C --> E[Result two]
```


```{dot}
//| echo: true
//| ht-pattern: "//<<"
graph G {
  layout=neato
  run -- intr;
  intr -- runbl;
  runbl -- run;
  run -- kernel;
  kernel -- zombie;
  kernel -- sleep;
  kernel -- runmem; //<<
  sleep -- swap;
  swap -- runswap;
  runswap -- new;
  runswap -- runmem;
  new -- runmem; //<<
  sleep -- runmem;
}
```


It is also possible to use `#<<` to highlight lines in syntatically formatted markdown code blocks,

```{.r}
library(dplyr)

iris |> #<<
  group_by(Species) |> 
  summarize(mean(Sepal.Length)) #<<
```


```{.python .numberLines}
print("Hello world")

for name in ["Sam", "Jake"]: #<<
    print(f"Hello {name}!")
```


## Highlighting Output Line Numbers

Highlighting output line numbers a bit tricky. To enable output line number highlighting, we need to use both output class `highlight` and `numberLines` along with `output-line-numbers`.


#### Example 01

So to highlight second line of output, we use `output-line-numbers: "2"` and `class-output: "highlight numberLines"` (Sorry couldn't make it any more easier :D :p).


```{r}
#| source-line-numbers: "1,3"
#| class-output: "highlight numberLines"
#| output-line-numbers: "2"

mtcars |> 
  summarize(
    avg_mpg = mean(mpg)
  )
```


#### Example 02


```{r}
#| source-line-numbers: "2"
#| class-source: "numberLines"
#| class-output: "highlight numberLines"
#| output-line-numbers: "1-3"

iris |> 
  group_by(Species) |> 
  summarize(mean(Sepal.Length))
```


## Code Blocks within the `panel-tabset`, `callout-blocks`

To get the line-highlighting for code blocks within the `panel-tabset`s or Callout Blocks, you need to run the `line-highlight` filter after the `quarto` filter, like this,

``` yaml
---
[..other options..]
filters:
  - quarto
  - line-highlight
[..other options..]
---
```

> This document itself has been rendered by following above (since it contains examples for the case of `panel-tabset` and `callout-blocks`). You can verify it by clicking `</> Code` button on top-right corner

And then `line-highlight` will also work for code blocks within the panel tabsets and callout blocks.

### Panel Tabsets

::: panel-tabset

## Example 1

```{.r}
iris |> #<<
  head(5)
```

## Example 2

```{.r}
library(dplyr) #<<

# code
iris |> 
  group_by(Species) |> #<<
  summarize(mean(Sepal.Length))
```

:::


### Callout Blocks

::: callout-note

## Example 1

```{.r}
library(dplyr)

iris |> #<<
  group_by(Species) |> 
  summarize(mean(Sepal.Length)) #<<
```

:::


::: callout-note

## Example 2

```{.python source-line-numbers="3-4" .numberLines}
print("Hello world")

for name in ["Sam", "Jake"]:
    print(f"Hello {name}!")
```

:::

::: callout-note

## Example 3

```{.julia source-line-numbers="2-4" .numberLines}
for i = 1:100 #<<
    str = i % 3 == 0 ? "Fizz" : ""
    str *= i % 5 == 0 ? "Buzz" : ""
    if isempty(str)
        str = i
    end
    println(str) #<<
end
```

:::