# `MishkaDocument.Resources.Changes.HighlightCode`
[🔗](https://github.com/mishka-group/mishka_document/blob/v0.0.1/lib/mishka_document/resources/__changes/highlight_code.ex#L5)

Highlights the code blocks of a page's `content` — a section's, a note's or a draft of either — with Makeup,
once, when it is written.

A block is a `<pre>` holding one `<code class="language-x">` whose code is still plain text, and
whose language names a lexer Makeup has registered — by name (`elixir`, `iex`, `heex`, `eex`,
`erlang`, `erl`, `html`, `json`, `diff`, `sql`, `js`, `javascript`, `ts`, `typescript`, `css`) or
by file extension (`ex`, `exs`, `hrl`, `htm`, `patch`). It is stored as
`<pre class="highlight"><code class="language-x">` with one `<span class="…">` per token, the
classes the kit's `doc-code-highlight` stylesheet colours. Reading a page highlights nothing.

Left as written:

  * a block whose code already holds markup — highlighted here before;
  * a block with no `language-` class, or one no lexer answers to (`sh`, `bash`, `shell`…);
  * a `<code>` that is not the only thing in its `<pre>`, and inline `<code>`;
  * a block whose lexer raises or takes longer than five seconds. Each block is lexed in its own
    task under `MishkaDocument.HighlightSupervisor`, so that block stays plain and the page is
    still written.

## After the sanitizer

`content` is sanitized by the `guardedstruct` change, which Ash runs after every change an action
lists. This one does its work in a `before_action` hook, which runs after all of them, so what it
reads is the sanitizer's HTML: attributes double-quoted, and text escaped as `&amp;`, `&lt;` and
`&gt;` and nothing else. The blocks are found in that shape and the tokens are written in it, so
the code stays text — a `<script>` in a code block is `&lt;script&gt;` before and after — and
saving a highlighted page again leaves its content as it is.

## Usage

    update :update do
      change MishkaDocument.Resources.Changes.HighlightCode
    end

# `highlight`

```elixir
@spec highlight(String.t()) :: String.t()
```

`html` with every plain code block of a known language highlighted, and nothing else changed.

---

*Consult [api-reference.md](api-reference.md) for complete listing*