|
| 1 | ++++ |
| 2 | +description = "Generate diagrams and flowcharts from text" |
| 3 | +title = "Highlight" |
| 4 | ++++ |
| 5 | + |
| 6 | +The `highlight` shortcode renders your code with a syntax highlighter. |
| 7 | + |
| 8 | +{{< highlight lineNos="table" type="py" wrap="true" >}} |
| 9 | +print("Hello World!") |
| 10 | +{{< /highlight >}} |
| 11 | + |
| 12 | +## Usage |
| 13 | + |
| 14 | +This shortcode is compatible with Hugo's [`highlight` shortcode](https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode) but offers some extensions. |
| 15 | + |
| 16 | +You can call it interchangeably in the same way as Hugo's own shortcode using positional parameter or by simply using codefences. |
| 17 | + |
| 18 | +You are free to also call this shortcode from your own partials. In this case it somewhat resemble Hugo's [`highlight` function](https://gohugo.io/functions/highlight/) syntax if you call this shortcode as a partial using compatiblity syntax. |
| 19 | + |
| 20 | +While the examples are using shortcodes with named parameter it is recommended to use codefences instead. This is because more and more other software supports codefences (eg. GitHub) and so your markdown becomes more portable. |
| 21 | + |
| 22 | + |
| 23 | +{{< tabs groupId="shortcode-parameter">}} |
| 24 | +{{% tab title="codefence" %}} |
| 25 | + |
| 26 | +````md |
| 27 | +```py { lineNos="table" wrap="true" } |
| 28 | +print("Hello World!") |
| 29 | +``` |
| 30 | +```` |
| 31 | + |
| 32 | +{{% /tab %}} |
| 33 | +{{% tab title="shortcode" %}} |
| 34 | + |
| 35 | +````go |
| 36 | +{{</* highlight lineNos="table" type="py" wrap="true" */>}} |
| 37 | +print("Hello World!") |
| 38 | +{{</* /highlight */>}} |
| 39 | +```` |
| 40 | + |
| 41 | +{{% /tab %}} |
| 42 | +{{% tab title="shortcode (positional)" %}} |
| 43 | + |
| 44 | +````go |
| 45 | +{{</* highlight py "lineNos=table,wrap=true" */>}} |
| 46 | +print("Hello World!") |
| 47 | +{{</* /highlight */>}} |
| 48 | +```` |
| 49 | + |
| 50 | +{{% /tab %}} |
| 51 | +{{% tab title="partial" %}} |
| 52 | + |
| 53 | +````go |
| 54 | +{{ partial "shortcodes/highlight.html" (dict |
| 55 | + "context" . |
| 56 | + "content" "print(\"Hello World!\")" |
| 57 | + "lineNos" "table" |
| 58 | + "type" "py" |
| 59 | + "wrap" "true" |
| 60 | +)}} |
| 61 | + |
| 62 | +```` |
| 63 | + |
| 64 | +{{% /tab %}} |
| 65 | +{{% tab title="partial (compat)" %}} |
| 66 | + |
| 67 | +````go |
| 68 | +{{ partial "shortcodes/highlight.html" (dict |
| 69 | + "context" . |
| 70 | + "content" "print(\"Hello World!\")" |
| 71 | + "options" "lineNos=table,wrap=true" |
| 72 | + "type" "py" |
| 73 | +)}} |
| 74 | + |
| 75 | +```` |
| 76 | + |
| 77 | +{{% /tab %}} |
| 78 | +{{< /tabs >}} |
| 79 | + |
| 80 | +### Parameter |
| 81 | + |
| 82 | +| Name | Default | Notes | |
| 83 | +|:----------------------|:-----------------|:------------| |
| 84 | +| **type** | _<empty>_ | The language of the code to highlight. Choose from one of the [supported languages](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages). Case-insensitive. | |
| 85 | +| **wrap** | see notes | _Extension_. When `true` the content may wrap on long lines otherwise it will be scrollable.<br><br>The default value can be set in your `config.toml` and overwritten via frontmatter. [See below](#configuration). | |
| 86 | +| **options** | _<empty>_ | An optional, comma-separated list of zero or more [Hugo supported options](https://gohugo.io/functions/highlight/#options) as well as extension parameter from this table. | |
| 87 | +| _**<option>**_ | _<empty>_ | Any of [Hugo's supported options](https://gohugo.io/functions/highlight/#options). | |
| 88 | +| _**<content>**_ | _<empty>_ | Your code to highlight. | |
| 89 | + |
| 90 | +## Configuration |
| 91 | + |
| 92 | +Default values for [Hugo's supported options](https://gohugo.io/functions/highlight/#options) can be set via [goldmark settings](https://gohugo.io/getting-started/configuration-markup/#highlight) in your `config.toml` |
| 93 | + |
| 94 | +Default values for extension options can be set via params settings in your `config.toml` or be overwritten by frontmatter for each individual page. |
| 95 | + |
| 96 | +### Global Configuration File |
| 97 | + |
| 98 | +#### Recommended Settings |
| 99 | + |
| 100 | +````toml |
| 101 | +[markup] |
| 102 | + [markup.highlight] |
| 103 | + # line numbers in a table layout will shift if code is wrapping, so better |
| 104 | + # use inline; besides that visually both layouts have the same look and behavior |
| 105 | + lineNumbersInTable = false |
| 106 | + |
| 107 | + # if `guessSyntax = true`, there will be no unstyled code even if no language |
| 108 | + # was given BUT Mermaid and Math codefences will not work anymore! So this is a |
| 109 | + # mandatory setting for your site if you want to use Mermaid or Math codefences |
| 110 | + guessSyntax = false |
| 111 | + |
| 112 | + # the shipped variants come with their own modified chroma syntax highlightning |
| 113 | + # style which is imported in theme-relearn-light.css, theme-relearn-dark.css, etc.; |
| 114 | + # if you want to use a predefined style instead: |
| 115 | + # - remove `noClasses` or set `noClasses = true` |
| 116 | + # - set `style` to a predefined style name |
| 117 | + noClasses = false |
| 118 | + # style = "tango" |
| 119 | +```` |
| 120 | + |
| 121 | +#### Optional Settings |
| 122 | + |
| 123 | +````toml |
| 124 | +[params] |
| 125 | + highlightWrap = true |
| 126 | +```` |
| 127 | + |
| 128 | +### Page's Frontmatter |
| 129 | + |
| 130 | +````toml |
| 131 | ++++ |
| 132 | +highlightWrap = true |
| 133 | ++++ |
| 134 | +```` |
| 135 | + |
| 136 | +## Examples |
| 137 | + |
| 138 | +### Line Numbers |
| 139 | + |
| 140 | +As mentioned above, line numbers in a `table` layout will shift if code is wrapping, so better use `inline`. To make things easier for you, set `lineNumbersInTable = false` in your `config.toml` and add `lineNos = true` when calling the shortcode instead of the specific values `table` or `inline`. |
| 141 | + |
| 142 | +````go |
| 143 | +{{</* highlight lineNos="true" type="py" */>}} |
| 144 | +# Quicksort Python One-liner |
| 145 | +lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]]) |
| 146 | +# Some more stuff |
| 147 | +{{</* /highlight */>}} |
| 148 | +```` |
| 149 | + |
| 150 | +{{< highlight lineNos="true" type="py" >}} |
| 151 | +# Quicksort Python One-liner |
| 152 | +lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]]) |
| 153 | +# Some more stuff |
| 154 | +{{< /highlight >}} |
| 155 | + |
| 156 | +### With Wrap |
| 157 | + |
| 158 | +````go |
| 159 | +{{</* highlight type="py" wrap="true" hl_lines="2" */>}} |
| 160 | +# Quicksort Python One-liner |
| 161 | +lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]]) |
| 162 | +# Some more stuff |
| 163 | +{{</* /highlight */>}} |
| 164 | +```` |
| 165 | + |
| 166 | +{{< highlight type="py" wrap="true" hl_lines="2" >}} |
| 167 | +# Quicksort Python One-liner |
| 168 | +lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]]) |
| 169 | +# Some more stuff |
| 170 | +{{< /highlight >}} |
| 171 | + |
| 172 | +### Without Wrap |
| 173 | + |
| 174 | +````go |
| 175 | +{{</* highlight type="py" wrap="false" hl_lines="2" */>}} |
| 176 | +# Quicksort Python One-liner |
| 177 | +lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]]) |
| 178 | +# Some more stuff |
| 179 | +{{</* /highlight */>}} |
| 180 | +```` |
| 181 | + |
| 182 | +{{< highlight type="py" wrap="false" hl_lines="2">}} |
| 183 | +# Quicksort Python One-liner |
| 184 | +lambda L: [] if L==[] else qsort([x for x in L[1:] if x< L[0]]) + L[0:1] + qsort([x for x in L[1:] if x>=L[0]]) |
| 185 | +# Some more stuff |
| 186 | +{{< /highlight >}} |
0 commit comments