diff --git a/doc/doc-setupfile.org b/doc/doc-setupfile.org index 33c88900..8dccff1a 100644 --- a/doc/doc-setupfile.org +++ b/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*]] diff --git a/doc/ox-hugo-manual.org b/doc/ox-hugo-manual.org index 495c4663..fb110eb3 100644 --- a/doc/ox-hugo-manual.org +++ b/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 :" 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 diff --git a/ox-hugo.el b/ox-hugo.el index 6d73acd7..6f4e3c85 100644 --- a/ox-hugo.el +++ b/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 diff --git a/test/site/content/posts/coderef.md b/test/site/content/posts/coderef.md index 7bae902f..65316d9c 100644 --- a/test/site/content/posts/coderef.md +++ b/test/site/content/posts/coderef.md @@ -25,10 +25,10 @@ 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. @@ -36,10 +36,10 @@ 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. @@ -47,10 +47,10 @@ 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. @@ -58,10 +58,10 @@ 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.