Document how to enable AsciiDoc syntax highlighting

jmooring · Aug 25, 2024 · 22991a4 · 22991a4
1 parent c3350f4
commit 22991a4
Showing 1 changed file with 45 additions and 0 deletions.
diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md
@@ -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: