example.qmd

---
title: "Highlight-text Quarto Extension"
format:
  html:
    output-file: index
  typst:
    output-file: highlight-typst
    papersize: a4
    margin:
      x: 2.5cm
      y: 2.5cm
  pdf-xelatex:
    output-file: highlight-xelatex
    papersize: a4
    margin:
      x: 2.5cm
      y: 2.5cm
  pdf-lualatex:
    output-file: highlight-lualatex
    pdf-engine: lualatex
    papersize: a4
    margin:
      x: 2.5cm
      y: 2.5cm
  pdf-pdflatex:
    output-file: highlight-pdflatex
    pdf-engine: lualatex
    papersize: a4
    margin:
      x: 2.5cm
      y: 2.5cm
  docx:
    output-file: highlight-docx
  revealjs:
    output-file: highlight-revealjs
  beamer:
    output-file: highlight-beamer
    aspectratio: 169
  pptx:
    output-file: highlight-pptx
format-links:
  - html
  - typst
  - format: pdf-xelatex
    text: "PDF (XeLaTeX)"
  - format: pdf-lualatex
    text: "PDF (LuaLaTeX)"
  - format: pdf-pdflatex
    text: "PDF (PDFLaTeX)"
  - docx
  - revealjs
  - beamer
  - pptx
embed-resources: true
execute:
  echo: true
filters:
  - highlight-text
brand:
  light:
    color:
      palette:
        fg: "#ffffff"
        bg: "#b22222"
      foreground: "#333333"
      background: "#fafafa"
  dark:
    color:
      palette:
        fg: "#b22222"
        bg: "#ffffff"
      foreground: "#fafafa"
      background: "#333333"
---

This is a Quarto extension that allows to highlight text in a document for various format: HTML, LaTeX, Typst, and Docx.

## Installing

```bash
quarto add mcanouil/quarto-highlight-text
```

This will install the extension under the `_extensions` subdirectory.
If you're using version control, you will want to check in this directory.

## Using

To use the extension, add the following to your document's front matter:

```yaml
filters:
  - highlight-text
```

Then you can use the span syntax markup to highlight text in your document.

```markdown
[Red]{colour="#b22222" bg-colour="#abc123"} # UK
[Red]{fg="#b22222" bg="#abc123"}
[Blue]{color="#0000FF" bg-color="#ABC123"} # US
```

## Font Colour

```markdown
[Red text]{colour="#b22222"}
```

[Red text]{colour="#b22222"}

```markdown
[Blue text]{color="#0000FF"}
```

[Blue text]{color="#0000FF"}

## Background Colour

```markdown
[Red background]{bg-colour="#b22222"}
```

[Red background]{bg-colour="#b22222"}

```markdown
[Blue background]{bg-color="#0000FF"}
```

[Blue background]{bg-color="#0000FF"}

## Font and Background Colour

```markdown
[White text, Red background]{
  fg="#FFFFFF" bg="#b22222"
}
```

[White text, Red background]{fg="#FFFFFF" bg="#b22222"}

```markdown
[White text, Blue background]{
  colour="#FFFFFF" bg-colour="#0000FF"
}
```

[White text, Blue background]{colour="#FFFFFF" bg-colour="#0000FF"}

## More Examples

```markdown
[text [with a link](https://quarto.org/)]{
  color="#FFFFFF" bg-color="#00FFFF"
}
```

[text [with a link](https://quarto.org/)]{
  color="#FFFFFF" bg-color="#00FFFF"
}

## `_brand.yml`

```markdown
[Light: White/Red | Dark: Red/White]{
  colour="brand-color.fg"
  bg-colour="brand-color.bg"
}
```

[Light: White/Red | Dark: Red/White]{colour="brand-color.fg" bg-colour="brand-color.bg"}

## Limitations `xelatex` and `pdflatex`

LaTeX `\colorbox` command does not support wrapping/line breaks in the text to be highlighted.
This means that the above example will not work well in LaTeX output.

```markdown
[Your long text]{colour="#b22222" bg-colour="#abc123"}
```
[
  LaTeX `\colorbox` command does not support wrapping/line breaks in the text to be highlighted.
This means that the above example will not work well in LaTeX output.
]{colour="#b22222" bg-colour="#abc123"}

In order to get a slightly better result, you can use the `par=true` attribute to add `\parbox{\linewidth}`:

```markdown
[Your long text]{colour="#b22222" bg-colour="#abc123" par=true}
```

[
  LaTeX `\colorbox` command does not support wrapping/line breaks in the text to be highlighted.
This means that the above example will not work well in LaTeX output.
]{colour="#b22222" bg-colour="#abc123" par=true}

Use `pdf-engine: lualatex` in the YAML front matter to get the best result.