Merge pull request #577 from kaushalmodi/use-code-fences-for-coderefs

breaking: minor: Now code fences are used even when using coderefs Hugo v0.93.0+

doc/doc-setupfile.org

@@ -1,6 +1,6 @@
 #+macro: min_emacs_version *25.3*
 #+macro: min_org_version *9.0*
-#+macro: min_hugo_version [[https://github.com/gohugoio/hugo/releases/tag/v0.60.0][*0.60.0*]]
+#+macro: min_hugo_version [[https://github.com/gohugoio/hugo/releases/tag/v0.93.0][*0.93.0*]]
 #+macro: org_mode_version [[https://git.savannah.gnu.org/cgit/emacs/org-mode.git/log/?h=bugfix][*9.5.1*]]
 #+macro: pandoc_version [[https://github.com/jgm/pandoc/releases/tag/2.16.2][*2.16.2*]]
 

doc/ox-hugo-manual.org

@@ -1180,8 +1180,7 @@ possible. It also supports exporting source blocks with line numbers
 and/or highlighting enabled for specific lines.
 **** Code Fences
 By default, the =HUGO_CODE_FENCE= property is non-nil. So the code
-blocks will be exported with GitHub-style code-fencing with
-triple-backticks when possible.
+blocks will be exported with /CommonMark/ code fences when possible.
 
 For example, below Org source block:
 
@@ -1203,9 +1202,6 @@ will export to:
   =markup.highlight.codeFences= to =true= (which is the default at
   least as of [[https://github.com/gohugoio/hugo/commit/bfb9613a14ab2d93a4474e5486d22e52a9d5e2b3][Hugo v0.60.0]]) for syntax highlighting to work for fenced
   code blocks.
-
-If you want to always use the Hugo [[#highlight-shortcode][=highlight= shortcode]], set the
-=HUGO_CODE_FENCE= property to =nil=.
 **** Line numbers
 Line numbers can be enabled/configured using the Org =-n= / =+n=
 syntax. See the Info node [[https://orgmode.org/manual/Literal-Examples.html][=(org) Literal Examples=]] for more
@@ -1249,11 +1245,11 @@ by adding =:linenos false= to their headers.
   ~inline~
 
 /The same =:linenos= header arg works for example blocks too./
-**** Highlighting
+**** Highlight Lines
 Implementing this feature was interesting, because while Org doesn't
 have a syntax to enable highlighting only specific lines, Hugo
-supports highlighting using the =hl_lines= attribute to [[https://gohugo.io/content-management/syntax-highlighting#highlighting-in-code-fences][code fences]]
-(Hugo v0.60.0+) or its ~highlight~ shortcode.
+supports line highlighting using the =hl_lines= attribute for [[https://gohugo.io/content-management/syntax-highlighting#highlighting-in-code-fences][code
+fences]] (Hugo v0.60.0+) or its ~highlight~ shortcode.
 
 So the challenge was to present that "lines to be highlighted"
 information in the Org source in a nice format and then translate that
@@ -1285,21 +1281,6 @@ The Org source for the below is similar to the above, except that the
 =-n= switch is also added to enable the line numbers.
 
 #+include: "../test/site/content-org/all-posts.org::#source-blocks-with-highlighting-with-linenums-not-starting-from-1" :only-contents t
-**** ~highlight~ shortcode
-:PROPERTIES:
-:CUSTOM_ID: highlight-shortcode
-:END:
-The Hugo [[https://gohugo.io/content-management/syntax-highlighting#highlight-shortcode][=highlight= shortcode]] is automatically used instead of code
-fences (even with this property at a non-nil value) if one of these is
-true:
-- ~HUGO_CODE_FENCE~ is set to /nil/.
-- "Blackfriday mode" is enabled (~HUGO_GOLDMARK~ is /nil/) *and*
-  either the [[*Line numbers][line numbering]] or [[*Highlighting][highlighting]] feature is enabled, or if
-  the [[#linenos][=:linenos= parameter]] is specified in the source block header.
-
-By default, ~ox-hugo~ tries to avoid using this shortcode because it's
-more bug-prone than the code fences ({{{issue(161)}}}), and also the
-code fences are more /Markdownish/ :smile:.
 **** Hiding source block caption numbers
 The "Code Snippet <number>:" part of the source block captions can be
 hidden by adding this to the CSS:
@@ -1385,6 +1366,22 @@ exports to:
 
 In line [[(sc1)]] we remember the current position. [[(jump1)][Line (jump1)]] jumps to
 ~point-min~.
+**** ~highlight~ shortcode
+:PROPERTIES:
+:CUSTOM_ID: highlight-shortcode
+:END:
+#+begin_note
+By default, ~ox-hugo~ tries to avoid using this shortcode because it
+is buggy ({{{issue(161)}}}), and also it's better to export
+/CommonMark/ supported code fences than Hugo-specific shortcodes.
+#+end_note
+The Hugo [[https://gohugo.io/content-management/syntax-highlighting#highlight-shortcode][=highlight= shortcode]] is used instead of code fences if one
+of these is true:
+- ~HUGO_CODE_FENCE~ is set to /nil/.
+- "Blackfriday mode" is enabled (~HUGO_GOLDMARK~ is /nil/) *and*
+  either of the [[*Line numbers][line numbering]], [[*Highlight Lines][line highlighting]] or [[*Code References][code ref]] features
+  are enabled, or if the [[#linenos][=:linenos= parameter]] is specified in the
+  source block header.
 *** Equations
 :PROPERTIES:
 :EXPORT_FILE_NAME: equations

ox-hugo.el

@@ -2839,28 +2839,20 @@ supported with code fences too.
 CONTENTS is nil.  INFO is a plist used as a communication
 channel.
 
---- Hugo v0.60.0 and newer ---
+--- When is the \"highlight\" shortcode needed? ---
 
-If using Hugo version v0.60.0 or newer (if `org-hugo-goldmark' is
-non-nil), the Hugo \"highlight\" shortcode is needed if,
-
-  - Coderefs are used.
-
---- Hugo older than v0.60.0 ---
-
-If using a Hugo version older than v0.60.0, the user *needs* to
-set the `pygmentsCodeFences' variable to `true' in their Hugo
-site's config.  Otherwise syntax highlighting will not work in
-the generated fenced code blocks!
-
-Hugo \"highlight\" shortcode is needed if `org-hugo-goldmark' is
-nil and,
+It's needed only in Blackfriday mode (`org-hugo-goldmark' is
+nil), and if any of these is true:
   - Code blocks with line numbers (if the -n or +n switch is used).
   - Highlight certains lines in the code block (if the :hl_lines
     parameter is used).
   - Set the `linenos' argument to the value passed by :linenos
     (defaults to `table').
-  - Coderefs are used."
+  - Coderefs are used.
+
+Note: If using a Hugo version older than v0.60.0, the user
+*needs* to set the `pygmentsCodeFences' variable to `true' in
+their Hugo site's config."
   (let* ((lang (org-element-property :language src-block))
          (parameters-str (org-element-property :parameters src-block))
          (parameters (org-babel-parse-header-arguments parameters-str))
@@ -2908,13 +2900,9 @@ nil and,
              ;; Use the `highlight' shortcode only if ..
              (use-highlight-sc (or ;; HUGO_CODE_FENCE is nil, or ..
                                 (null (org-hugo--plist-get-true-p info :hugo-code-fence))
-                                ;; code refs are used (code fences format
-                                ;; does not support code line
-                                ;; anchors! See https://discourse.gohugo.io/t/36564/3), or ..
-                                code-refs
                                 ;; "Blackfriday mode" is enabled and line numbering
-                                ;; or highlighting is needed.
-                                (and (or line-num-p hl-lines linenos-style)
+                                ;; , highlighting or code refs are needed.
+                                (and (or line-num-p hl-lines linenos-style code-refs)
                                      (not goldmarkp))))
              (hl-lines (when (stringp hl-lines)
                          (if use-highlight-sc

test/site/content/posts/coderef.md

@@ -25,43 +25,43 @@ parenthesis.
 
 ### Default line nums with coderef labels {#default-line-nums-with-coderef-labels}
 
-{{< highlight emacs-lisp "linenos=table, anchorlinenos=true, lineanchors=org-coderef--c1cbed" >}}
+```emacs-lisp { linenos=table, anchorlinenos=true, lineanchors=org-coderef--c1cbed }
 (save-excursion                 (sc)
    (goto-char (point-min))      (jump)
-{{< /highlight >}}
+```
 
 In line [sc](#org-coderef--c1cbed-1) we remember the current position. [Line jump](#org-coderef--c1cbed-2) jumps to
 point-min.
 
 
 ### Default line nums without coderef labels {#default-line-nums-without-coderef-labels}
 
-{{< highlight emacs-lisp "linenos=table, anchorlinenos=true, lineanchors=org-coderef--ea1413" >}}
+```emacs-lisp { linenos=table, anchorlinenos=true, lineanchors=org-coderef--ea1413 }
 (save-excursion
    (goto-char (point-min))
-{{< /highlight >}}
+```
 
 In line [1](#org-coderef--ea1413-1) we remember the current position. [Line 2](#org-coderef--ea1413-2) jumps to
 point-min.
 
 
 ### Custom line nums without coderef labels {#custom-line-nums-without-coderef-labels}
 
-{{< highlight emacs-lisp "linenos=table, linenostart=20, anchorlinenos=true, lineanchors=org-coderef--cc4270" >}}
+```emacs-lisp { linenos=table, linenostart=20, anchorlinenos=true, lineanchors=org-coderef--cc4270 }
 (save-excursion
    (goto-char (point-min))
-{{< /highlight >}}
+```
 
 In line [20](#org-coderef--cc4270-20) we remember the current position. [Line 21](#org-coderef--cc4270-21) jumps to
 point-min.
 
 
 ### Custom line nums without coderef labels and with highlighting {#custom-line-nums-without-coderef-labels-and-with-highlighting}
 
-{{< highlight emacs-lisp "linenos=table, linenostart=20, hl_lines=2, anchorlinenos=true, lineanchors=org-coderef--a1ac71" >}}
+```emacs-lisp { linenos=table, linenostart=20, hl_lines=["2"], anchorlinenos=true, lineanchors=org-coderef--a1ac71 }
 (save-excursion
    (goto-char (point-min))
-{{< /highlight >}}
+```
 
 [Line 21](#org-coderef--a1ac71-21) jumps to point-min.
 
@@ -71,17 +71,17 @@ point-min.
 In line [1](#org-coderef--4489bc-1) we remember the current position. [Line 2](#org-coderef--4489bc-2) jumps to
 point-min.
 
-{{< highlight emacs-lisp "linenos=table, anchorlinenos=true, lineanchors=org-coderef--4489bc" >}}
+```emacs-lisp { linenos=table, anchorlinenos=true, lineanchors=org-coderef--4489bc }
 (save-excursion
    (goto-char (point-min))
-{{< /highlight >}}
+```
 
 
 ## Example block {#example-block}
 
-{{< highlight text "linenos=table, linenostart=20, anchorlinenos=true, lineanchors=org-coderef--942ea6" >}}
+```text { linenos=table, linenostart=20, anchorlinenos=true, lineanchors=org-coderef--942ea6 }
 (save-excursion
    (goto-char (point-min))
-{{< /highlight >}}
+```
 
 [Line 21](#org-coderef--942ea6-21) jumps to point-min.