Document how to enable AsciiDoc syntax highlighting

2026-09-01 19:22:38 +00:00 · 2024-08-25 09:03:24 -07:00
parent c3350f4cfd
commit ca802fbec1
1 changed files with 45 additions and 0 deletions
@@ -302,6 +302,51 @@ To mitigate security risks, entries in the extension array may not contain forwa
        my-attribute-name = "my value"
 {{< /code-toggle >}}

+### AsciiDoc syntax highlighting
+
+Follow the steps below to enable syntax highlighting.
+
+Step 1
+: Set the `source-highlighter` attribute in your site configuration. For example:
+
+{{< code-toggle file=hugo >}}
+[markup.asciidocExt.attributes]
+source-highlighter = 'rouge'
+{{< /code-toggle >}}
+
+Step 2
+: Generate the highlighter CSS. For example:
+
+```text
+rougify style monokai.sublime > assets/css/syntax.css
+```
+
+Step 3
+: In your base template add a link to the CSS file:
+
+{{< code file=layouts/_default/baseof.html >}}
+<head>
+  ...
+  {{ with resources.Get "css/syntax.css" }}
+    <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
+  {{ end }}
+  ...
+</head>
+{{< /code >}}
+
+Then add the code to be highlighted to your markup:
+
+```text
+[#hello,ruby]
+----
+require 'sinatra'
+
+get '/hi' do
+  "Hello World!"
+end
+----
+```
+
 ### AsciiDoc troubleshooting

 Run `hugo --logLevel debug` to examine Hugo's call to the Asciidoctor executable: