Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 1 commit into from
Mar 1, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion doc/doc-setupfile.org
Original file line number Diff line number Diff line change
@@ -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*]]

Expand Down
43 changes: 20 additions & 23 deletions doc/ox-hugo-manual.org
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down
32 changes: 10 additions & 22 deletions ox-hugo.el
Original file line number Diff line number Diff line change
Expand Up @@ -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))
Expand Down Expand Up @@ -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
Expand Down
24 changes: 12 additions & 12 deletions test/site/content/posts/coderef.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.