From 1583d7f371c019eeb70e8fdc24804dbfdfc23de4 Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Tue, 4 Jan 2022 02:43:31 -0500 Subject: [PATCH 1/8] Example blocks use code fence instead of `highlight` if Goldmark Ref: https://github.com/kaushalmodi/ox-hugo/issues/305 Also see https://github.com/kaushalmodi/ox-hugo/discussions/485. --- ox-blackfriday.el | 11 +++++-- ox-hugo.el | 29 +++++++++++-------- test/site/content-org/all-posts.org | 7 +++++ .../posts/example-block-with-line-numbers.md | 27 ++++++++++------- 4 files changed, 50 insertions(+), 24 deletions(-) diff --git a/ox-blackfriday.el b/ox-blackfriday.el index d5646775..80e6aa69 100644 --- a/ox-blackfriday.el +++ b/ox-blackfriday.el @@ -641,12 +641,16 @@ information." (let* ((parent-element (org-export-get-parent example-block)) (parent-type (car parent-element)) (backticks (make-string org-blackfriday--code-block-num-backticks ?`)) - (example (org-export-format-code-default example-block info)) + (example (or (plist-get info :md-code) ;if set in `org-hugo-example-block' + (org-export-format-code-default example-block info))) + (code-attr (if (plist-get info :md-code-attr) ;if set in `org-hugo-example-block' + (format " { %s }" (plist-get info :md-code-attr)) + "")) ret) ;; (message "[ox-bf example-block DBG]") ;; (message "[ox-bf example-block DBG] parent type: %S" parent-type) (setq ret (org-blackfriday--issue-239-workaround example parent-type)) - (setq ret (format "%stext\n%s%s" backticks ret backticks)) + (setq ret (format "%stext%s\n%s%s" backticks code-attr ret backticks)) (setq ret (org-blackfriday--div-wrap-maybe example-block ret info)) (when (equal 'quote-block parent-type) ;; If the current example block is inside a quote block, future @@ -655,6 +659,9 @@ information." ;; for https://github.com/russross/blackfriday/issues/407. (setq org-blackfriday--code-block-num-backticks (1+ org-blackfriday--code-block-num-backticks))) + ;; Reset the temp info in the `info' plist + (plist-put info :md-code nil) + (plist-put info :md-code-attr nil) ret)) ;;;; Fixed Width diff --git a/ox-hugo.el b/ox-hugo.el index d1f9f117..0eac1961 100644 --- a/ox-hugo.el +++ b/ox-hugo.el @@ -1720,15 +1720,15 @@ channel." (defun org-hugo-example-block (example-block _contents info) "Transcode an EXAMPLE-BLOCK element into Markdown format. -If the example blocks are *not* set to be exported with line -numbers (See (org) Literal examples), Markdown style -triple-backquoted code blocks with \"text\" \\='language\\=' are -created. +Markdown style triple-backquoted code blocks with \"text\" +\\='language\\=' are created. -Otherwise, a \"text\" \\='language\\=' code block wrapped in Hugo -\"highlight\" shortcode (See -https://gohugo.io/content-management/syntax-highlighting) is -created. +If `org-hugo-goldmark' is nil and if the example blocks are *not* +set to be exported with line numbers (See (org) Literal +examples), a \"text\" \\='language\\=' code block wrapped in Hugo +\"highlight\" shortcode is created. + +See https://gohugo.io/content-management/syntax-highlighting#highlighting-in-code-fences. CONTENTS is nil. INFO is a plist holding contextual information." @@ -1738,23 +1738,28 @@ information." (linenos-style (and (org-string-nw-p switches-str) (string-match ":linenos\\s-+\\([^ ]+\\)\\b" switches-str) (match-string-no-properties 1 switches-str))) - linenos-str + code-attr-str ret) (if (or number-lines linenos-style) (let ((linenos-style (or linenos-style "table")) (text (org-export-format-code-default example-block info))) - (setq linenos-str (format "linenos=%s" linenos-style)) + (setq code-attr-str (format "linenos=%s" linenos-style)) (let ((linenostart-str (and ;Extract the start line number of the example block. (string-match "\\`\\([0-9]+\\)\\s-\\{2\\}" text) (match-string-no-properties 1 text)))) (when linenostart-str - (setq linenos-str (format "%s, linenostart=%s" linenos-str linenostart-str)))) + (setq code-attr-str (format "%s, linenostart=%s" code-attr-str linenostart-str)))) ;; Remove Org-inserted numbers from the beginning of each ;; line as the Hugo highlight shortcode will be used instead ;; of literally inserting the line numbers. (setq text (replace-regexp-in-string "^[0-9]+\\s-\\{2\\}" "" text)) - (setq text (format "{{< highlight text \"%s\" >}}\n%s{{< /highlight >}}\n" linenos-str text)) + (if (org-hugo--plist-get-true-p info :hugo-goldmark) + (progn + (plist-put info :md-code text) + (plist-put info :md-code-attr code-attr-str) + (setq text (org-blackfriday-example-block example-block nil info))) + (setq text (format "```{{< highlight text \"%s\" >}}\n%s{{< /highlight >}}\n" code-attr-str text))) (setq ret (org-blackfriday--div-wrap-maybe example-block text info))) (setq ret (org-blackfriday-example-block example-block nil info))) ret)) diff --git a/test/site/content-org/all-posts.org b/test/site/content-org/all-posts.org index b65e09b5..782b6558 100644 --- a/test/site/content-org/all-posts.org +++ b/test/site/content-org/all-posts.org @@ -1916,6 +1916,13 @@ This is an example line 1 line 2 #+end_example + +An example without ~-n~: + +#+begin_example +foo +bar +#+end_example *** Specify new line number start #+begin_example -n 20 line 20 diff --git a/test/site/content/posts/example-block-with-line-numbers.md b/test/site/content/posts/example-block-with-line-numbers.md index cb39c532..490fb299 100644 --- a/test/site/content/posts/example-block-with-line-numbers.md +++ b/test/site/content/posts/example-block-with-line-numbers.md @@ -10,40 +10,47 @@ draft = false ## Default new line number start {#default-new-line-number-start} -{{< highlight text "linenos=table, linenostart=1" >}} +```text { linenos=table, linenostart=1 } line 1 line 2 -{{< /highlight >}} +``` + +An example without `-n`: + +```text +foo +bar +``` ## Specify new line number start {#specify-new-line-number-start} -{{< highlight text "linenos=table, linenostart=20" >}} +```text { linenos=table, linenostart=20 } line 20 line 21 -{{< /highlight >}} +``` ## Default continued line numbers {#default-continued-line-numbers} -{{< highlight text "linenos=table, linenostart=22" >}} +```text { linenos=table, linenostart=22 } line 22 line 23 -{{< /highlight >}} +``` ## Specify continued line numbers jump {#specify-continued-line-numbers-jump} -{{< highlight text "linenos=table, linenostart=33" >}} +```text { linenos=table, linenostart=33 } line 33 line 34 -{{< /highlight >}} +``` ## Specifying `linenos` parameter {#specifying-linenos-parameter} -{{< highlight text "linenos=false" >}} +```text { linenos=false } This is line 1 This is line 2 This is line 3 -{{< /highlight >}} +``` From a9927fa6857d1d236553c90df0dfffd2fb7ccc7e Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Tue, 4 Jan 2022 12:35:32 -0500 Subject: [PATCH 2/8] example block: Fix a bug introduced in Blackfriday mode; refactor Add test case for highlight sc export for example block. --- ox-hugo.el | 47 ++++++++++--------- test/site/content-org/all-posts.org | 33 +++++++++++++ ...ample-blocks-with-attr-html-blackfriday.md | 34 ++++++++++++++ .../posts/example-blocks-with-attr-html.md | 15 +++++- 4 files changed, 106 insertions(+), 23 deletions(-) create mode 100644 test/site/content/posts/example-blocks-with-attr-html-blackfriday.md diff --git a/ox-hugo.el b/ox-hugo.el index 0eac1961..0ea14ea1 100644 --- a/ox-hugo.el +++ b/ox-hugo.el @@ -1738,29 +1738,34 @@ information." (linenos-style (and (org-string-nw-p switches-str) (string-match ":linenos\\s-+\\([^ ]+\\)\\b" switches-str) (match-string-no-properties 1 switches-str))) + (use-highlight-sc (and (or number-lines linenos-style) ;Use `highlight' shortcode only for Blackfriday if linenos is non-nil + (not (org-hugo--plist-get-true-p info :hugo-goldmark)))) + (example-code (org-export-format-code-default example-block info)) code-attr-str ret) - (if (or number-lines linenos-style) - (let ((linenos-style (or linenos-style "table")) - (text (org-export-format-code-default example-block info))) - (setq code-attr-str (format "linenos=%s" linenos-style)) - (let ((linenostart-str (and ;Extract the start line number of the example block. - (string-match "\\`\\([0-9]+\\)\\s-\\{2\\}" text) - (match-string-no-properties 1 text)))) - (when linenostart-str - (setq code-attr-str (format "%s, linenostart=%s" code-attr-str linenostart-str)))) - - ;; Remove Org-inserted numbers from the beginning of each - ;; line as the Hugo highlight shortcode will be used instead - ;; of literally inserting the line numbers. - (setq text (replace-regexp-in-string "^[0-9]+\\s-\\{2\\}" "" text)) - (if (org-hugo--plist-get-true-p info :hugo-goldmark) - (progn - (plist-put info :md-code text) - (plist-put info :md-code-attr code-attr-str) - (setq text (org-blackfriday-example-block example-block nil info))) - (setq text (format "```{{< highlight text \"%s\" >}}\n%s{{< /highlight >}}\n" code-attr-str text))) - (setq ret (org-blackfriday--div-wrap-maybe example-block text info))) + (when (or number-lines linenos-style) + ;; Default "linenos" style set to "table" if only number-lines + ;; is non-nil. + (setq linenos-style (or linenos-style "table")) + (setq code-attr-str (format "linenos=%s" linenos-style)) + (let ((linenostart-str (and ;Extract the start line number of the example block. + (string-match "\\`\\([0-9]+\\)\\s-\\{2\\}" example-code) + (match-string-no-properties 1 example-code)))) + (when linenostart-str + (setq code-attr-str (format "%s, linenostart=%s" code-attr-str linenostart-str)))) + + ;; Remove Org-inserted numbers from the beginning of each line + ;; as the Hugo highlight shortcode will be used instead of + ;; literally inserting the line numbers. + (setq example-code (replace-regexp-in-string "^[0-9]+\\s-\\{2\\}" "" example-code)) + (unless use-highlight-sc + (plist-put info :md-code example-code) + (plist-put info :md-code-attr code-attr-str))) + (if use-highlight-sc + (setq ret (org-blackfriday--div-wrap-maybe + example-block + (format "{{< highlight text \"%s\" >}}\n%s{{< /highlight >}}\n" code-attr-str example-code) + info)) (setq ret (org-blackfriday-example-block example-block nil info))) ret)) diff --git a/test/site/content-org/all-posts.org b/test/site/content-org/all-posts.org index 782b6558..85cc255b 100644 --- a/test/site/content-org/all-posts.org +++ b/test/site/content-org/all-posts.org @@ -1945,6 +1945,7 @@ This is line 2 This is line 3 #+end_example ** Example blocks with ATTR_HTML :attr___html:attr___css: +*** Example blocks with ATTR_HTML (Goldmark) :goldmark: :PROPERTIES: :EXPORT_FILE_NAME: example-blocks-with-attr-html :END: @@ -1959,6 +1960,38 @@ Line 3 #+end_example Some more text. + +#+attr_html: :class heavy +#+attr_css: :font-weight bold +#+begin_example -n +This is an example +Line 2 +Line 3 +#+end_example +*** Example blocks with ATTR_HTML (Blackfriday) :blackfriday: +:PROPERTIES: +:EXPORT_FILE_NAME: example-blocks-with-attr-html-blackfriday +:EXPORT_HUGO_GOLDMARK: +:END: +Some text. + +#+attr_html: :class indent-block +#+attr_css: :padding-left 50px +#+begin_example +This is an example +Line 2 +Line 3 +#+end_example + +Some more text. + +#+attr_html: :class heavy +#+attr_css: :font-weight bold +#+begin_example -n +This is an example +Line 2 +Line 3 +#+end_example * Menu in front matter :menu: ** Menu Meta Data in TOML Front Matter :PROPERTIES: diff --git a/test/site/content/posts/example-blocks-with-attr-html-blackfriday.md b/test/site/content/posts/example-blocks-with-attr-html-blackfriday.md new file mode 100644 index 00000000..f6adbb72 --- /dev/null +++ b/test/site/content/posts/example-blocks-with-attr-html-blackfriday.md @@ -0,0 +1,34 @@ ++++ +title = "Example blocks with ATTR_HTML (Blackfriday)" +tags = ["example", "attr_html", "attr_css", "blackfriday"] +draft = false ++++ + +Some text. + + + +
+
+ +```text +This is an example +Line 2 +Line 3 +``` +
+ +Some more text. + + + +
+
+ +{{< highlight text "linenos=table, linenostart=1" >}} +This is an example +Line 2 +Line 3 +{{< /highlight >}} + +
diff --git a/test/site/content/posts/example-blocks-with-attr-html.md b/test/site/content/posts/example-blocks-with-attr-html.md index 5912d015..cfaa8fef 100644 --- a/test/site/content/posts/example-blocks-with-attr-html.md +++ b/test/site/content/posts/example-blocks-with-attr-html.md @@ -1,6 +1,6 @@ +++ -title = "Example blocks with ATTR_HTML" -tags = ["example", "attr_html", "attr_css"] +title = "Example blocks with ATTR_HTML (Goldmark)" +tags = ["example", "attr_html", "attr_css", "goldmark"] draft = false +++ @@ -18,3 +18,14 @@ Line 3 Some more text. + + + +
+ +```text { linenos=table, linenostart=1 } +This is an example +Line 2 +Line 3 +``` +
From ee4a89529673fd89b444f762cdc7cc302592cf6b Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Tue, 4 Jan 2022 15:35:22 -0500 Subject: [PATCH 3/8] Add test for "Blackfriday mode" annotated src block export --- test/site/content-org/all-posts.org | 64 +++++++++- ...rce-block-with-line-numbers-blackfriday.md | 110 ++++++++++++++++++ .../posts/source-block-with-line-numbers.md | 5 +- 3 files changed, 174 insertions(+), 5 deletions(-) create mode 100644 test/site/content/posts/source-block-with-line-numbers-blackfriday.md diff --git a/test/site/content-org/all-posts.org b/test/site/content-org/all-posts.org index 85cc255b..5b469b0a 100644 --- a/test/site/content-org/all-posts.org +++ b/test/site/content-org/all-posts.org @@ -1314,6 +1314,65 @@ This code block once again contains no backticks: #+begin_src emacs-lisp (message "Hello again x6") #+end_src +** Source block annotations :src_block:annotations: +*** Source blocks with line number annotation :linenum: +**** Source blocks with line number annotation (Goldmark) :goldmark: +:PROPERTIES: +:EXPORT_FILE_NAME: source-block-with-line-numbers +:END: +- [[https://orgmode.org/manual/Literal-examples.html][Org reference]] +***** Cases +:PROPERTIES: +:CUSTOM_ID: source-block-line-number-cases +:END: +****** Default new line number start +******* Org source +#+begin_src org :noweb yes +<> +#+end_src +******* Output +#+begin_src org :noweb yes :exports results :results output replace :eval yes +<> +#+end_src +****** Specify new line number start +******* Org source +#+begin_src org :noweb yes +<> +#+end_src +******* Output +#+begin_src org :noweb yes :exports results :results output replace :eval yes +<> +#+end_src +****** Default continued line numbers +******* Org source +#+begin_src org :noweb yes +<> +#+end_src +******* Output +#+begin_src org :noweb yes :exports results :results output replace :eval yes +<> +#+end_src +****** Specify continued line numbers jump +******* Org source +#+begin_src org :noweb yes +<> +#+end_src +******* Output +#+begin_src org :noweb yes :exports results :results output replace :eval yes +<> +#+end_src +***** Specifying ~linenos~ parameter +#+begin_src emacs-lisp :linenos false +(message "This is line 1") +(message "This is line 2") +(message "This is line 3") +#+end_src + +#+begin_src emacs-lisp -n 30 :linenos inline +(message "This is line 30") +(message "This is line 31") +(message "This is line 32") +#+end_src ** Highlight Shortcode :highlight:shortcode: *** Source blocks with =highlight= shortcode :PROPERTIES: @@ -1329,9 +1388,10 @@ property needs to be left *empty* instead of setting to =nil=! :END: #+end_example #+include: "./all-posts.org::#example-text-with-code-blocks" :only-contents t -*** Source blocks with line number annotation +*** Source blocks with line number annotation (Blackfriday) :blackfriday:linenum: :PROPERTIES: -:EXPORT_FILE_NAME: source-block-with-line-numbers +:EXPORT_FILE_NAME: source-block-with-line-numbers-blackfriday +:EXPORT_HUGO_GOLDMARK: :END: - [[https://orgmode.org/manual/Literal-examples.html][Org reference]] - [[https://gohugo.io/content-management/syntax-highlighting/][Hugo =highlight= shortcode with line numbers]] diff --git a/test/site/content/posts/source-block-with-line-numbers-blackfriday.md b/test/site/content/posts/source-block-with-line-numbers-blackfriday.md new file mode 100644 index 00000000..77b3860e --- /dev/null +++ b/test/site/content/posts/source-block-with-line-numbers-blackfriday.md @@ -0,0 +1,110 @@ ++++ +title = "Source blocks with line number annotation (Blackfriday)" +tags = ["src-block", "highlight", "shortcode", "blackfriday", "linenum"] +draft = false ++++ + +- [Org reference](https://orgmode.org/manual/Literal-examples.html) +- [Hugo `highlight` shortcode with line numbers](https://gohugo.io/content-management/syntax-highlighting/) + + +## Cases {#source-block-line-number-cases} + + +### Default new line number start {#default-new-line-number-start} + + +#### Org source {#org-source} + +```org +#+begin_src emacs-lisp -n +;; this will export with line number 1 (default) +(message "This is line 2") +#+end_src +``` + + +#### Output {#output} + +{{< highlight emacs-lisp "linenos=table, linenostart=1" >}} +;; this will export with line number 1 (default) +(message "This is line 2") +{{< /highlight >}} + + +### Specify new line number start {#specify-new-line-number-start} + + +#### Org source {#org-source} + +```org +#+begin_src emacs-lisp -n 20 +;; this will export with line number 20 +(message "This is line 21") +#+end_src +``` + + +#### Output {#output} + +{{< highlight emacs-lisp "linenos=table, linenostart=20" >}} +;; this will export with line number 20 +(message "This is line 21") +{{< /highlight >}} + + +### Default continued line numbers {#default-continued-line-numbers} + + +#### Org source {#org-source} + +```org +#+begin_src emacs-lisp +n +;; This will be listed as line 22 +(message "This is line 23") +#+end_src +``` + + +#### Output {#output} + +{{< highlight emacs-lisp "linenos=table, linenostart=22" >}} +;; This will be listed as line 22 +(message "This is line 23") +{{< /highlight >}} + + +### Specify continued line numbers jump {#specify-continued-line-numbers-jump} + + +#### Org source {#org-source} + +```org +#+begin_src emacs-lisp +n 10 +;; This will be listed as line 33 +(message "This is line 34") +#+end_src +``` + + +#### Output {#output} + +{{< highlight emacs-lisp "linenos=table, linenostart=33" >}} +;; This will be listed as line 33 +(message "This is line 34") +{{< /highlight >}} + + +## Specifying `linenos` parameter {#specifying-linenos-parameter} + +{{< highlight emacs-lisp "linenos=false" >}} +(message "This is line 1") +(message "This is line 2") +(message "This is line 3") +{{< /highlight >}} + +{{< highlight emacs-lisp "linenos=inline, linenostart=30" >}} +(message "This is line 30") +(message "This is line 31") +(message "This is line 32") +{{< /highlight >}} diff --git a/test/site/content/posts/source-block-with-line-numbers.md b/test/site/content/posts/source-block-with-line-numbers.md index a2cb4343..5d0f0ece 100644 --- a/test/site/content/posts/source-block-with-line-numbers.md +++ b/test/site/content/posts/source-block-with-line-numbers.md @@ -1,11 +1,10 @@ +++ -title = "Source blocks with line number annotation" -tags = ["src-block", "highlight", "shortcode"] +title = "Source blocks with line number annotation (Goldmark)" +tags = ["src-block", "annotations", "linenum", "goldmark"] draft = false +++ - [Org reference](https://orgmode.org/manual/Literal-examples.html) -- [Hugo `highlight` shortcode with line numbers](https://gohugo.io/content-management/syntax-highlighting/) ## Cases {#source-block-line-number-cases} From fb728eabbacb1cb2a85db8d20b97ed0e6cd4e5c0 Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Tue, 4 Jan 2022 16:52:14 -0500 Subject: [PATCH 4/8] org-hugo-example-block: Remove b-o-l line nums only when enabled --- ox-hugo.el | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/ox-hugo.el b/ox-hugo.el index 0ea14ea1..aa55e028 100644 --- a/ox-hugo.el +++ b/ox-hugo.el @@ -1754,10 +1754,11 @@ information." (when linenostart-str (setq code-attr-str (format "%s, linenostart=%s" code-attr-str linenostart-str)))) - ;; Remove Org-inserted numbers from the beginning of each line - ;; as the Hugo highlight shortcode will be used instead of - ;; literally inserting the line numbers. - (setq example-code (replace-regexp-in-string "^[0-9]+\\s-\\{2\\}" "" example-code)) + (when number-lines + ;; Remove Org-inserted numbers from the beginning of each line + ;; as the Hugo highlight shortcode will be used instead of + ;; literally inserting the line numbers. + (setq example-code (replace-regexp-in-string "^[0-9]+\\s-\\{2\\}" "" example-code))) (unless use-highlight-sc (plist-put info :md-code example-code) (plist-put info :md-code-attr code-attr-str))) From f959758f54f0fcf6e776d96a5f375293c7ab6e79 Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Tue, 4 Jan 2022 15:19:19 -0500 Subject: [PATCH 5/8] Refactor `org-hugo-src-block` and `org-blackfriday-src-block` No functional change Refactoring done for better code clarity and to prep up for the changes needed in src block export for https://github.com/kaushalmodi/ox-hugo/issues/305. --- ox-blackfriday.el | 19 +++-- ox-hugo.el | 176 ++++++++++++++++++++++++---------------------- 2 files changed, 105 insertions(+), 90 deletions(-) diff --git a/ox-blackfriday.el b/ox-blackfriday.el index 80e6aa69..b5b327f2 100644 --- a/ox-blackfriday.el +++ b/ox-blackfriday.el @@ -647,7 +647,6 @@ information." (format " { %s }" (plist-get info :md-code-attr)) "")) ret) - ;; (message "[ox-bf example-block DBG]") ;; (message "[ox-bf example-block DBG] parent type: %S" parent-type) (setq ret (org-blackfriday--issue-239-workaround example parent-type)) (setq ret (format "%stext%s\n%s%s" backticks code-attr ret backticks)) @@ -659,7 +658,7 @@ information." ;; for https://github.com/russross/blackfriday/issues/407. (setq org-blackfriday--code-block-num-backticks (1+ org-blackfriday--code-block-num-backticks))) - ;; Reset the temp info in the `info' plist + ;; Reset the temp info in the `info' plist. (plist-put info :md-code nil) (plist-put info :md-code-attr nil) ret)) @@ -1061,7 +1060,11 @@ This function is adapted from `org-html-special-block'." INFO is a plist used as a communication channel." (let* ((lang (org-element-property :language src-block)) (lang (or (cdr (assoc lang org-blackfriday-syntax-highlighting-langs)) lang)) - (code (org-export-format-code-default src-block info)) + (code (or (plist-get info :md-code) ;if set in `org-hugo-src-block' + (org-export-format-code-default src-block info))) + (code-attr (if (plist-get info :md-code-attr) ;if set in `org-hugo-src-block' + (format " { %s }" (plist-get info :md-code-attr)) + "")) (parent-element (org-export-get-parent src-block)) (parent-type (car parent-element)) (num-backticks-in-code (when (string-match "^[[:blank:]]*\\(`\\{3,\\}\\)" code) @@ -1081,19 +1084,21 @@ INFO is a plist used as a communication channel." (<= org-blackfriday--code-block-num-backticks num-backticks-in-code)) (setq org-blackfriday--code-block-num-backticks (1+ num-backticks-in-code))) (setq backticks (make-string org-blackfriday--code-block-num-backticks ?`)) - ;; (message "[ox-bf src-block DBG]") - ;; (message "ox-bf [dbg] code: %s" code) + ;; (message "[ox-bf src-block DBG] code: %s" code) ;; (message "[ox-bf src-block DBG] parent type: %S" parent-type) (setq code (org-blackfriday--issue-239-workaround code parent-type)) (prog1 - (format "%s%s\n%s%s" backticks lang code backticks) + (format "%s%s%s\n%s%s" backticks lang code-attr code backticks) (when (equal 'quote-block parent-type) ;; If the current code block is inside a quote block, future ;; example/code blocks (especially the ones outside this quote ;; block) will require higher number of backticks. Workaround ;; for https://github.com/russross/blackfriday/issues/407. (setq org-blackfriday--code-block-num-backticks - (1+ org-blackfriday--code-block-num-backticks)))))) + (1+ org-blackfriday--code-block-num-backticks))) + ;; Reset the temp info in the `info' plist. + (plist-put info :md-code nil) + (plist-put info :md-code-attr nil)))) ;;;; Strike-Through (defun org-blackfriday-strike-through (_strike-through contents _info) diff --git a/ox-hugo.el b/ox-hugo.el index aa55e028..7f476686 100644 --- a/ox-hugo.el +++ b/ox-hugo.el @@ -2691,61 +2691,74 @@ communication channel." The Markdown style triple-backquoted code blocks are created if: - If the HUGO_CODE_FENCE property is set to a non-nil value (default), - - *AND* if none of the Hugo \"highlight\" shortcode features - are needed (see below). + - *AND* if the Hugo \"highlight\" shortcode is not needed (see + below). -The code block is wrapped in Hugo \"highlight\" shortcode (See -https://gohugo.io/content-management/syntax-highlighting) if one -of the above conditions is false. +Hugo v0.60.0 onwards, the `markup.highlight.codeFences' (new name +for the old `pygmentsCodeFences') config variable defaults to +true. See +https://gohugo.io/content-management/syntax-highlighting#highlighting-in-code-fences. +Attributes like highlighting code, \"linenos\", etc. are now +supported with code fences too. + +CONTENTS is nil. INFO is a plist used as a communication +channel. + +--- Hugo older than v0.60.0 --- -If using a Hugo version older than v0.60.0, note that even with -the default non-nil value of HUGO_CODE_FENCE, the user *needs* to +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 v0.60.0 onwards, the `markup.highlight.codeFences' (new name -for the old `pygmentsCodeFences') config variable defaults to -true. - -Hugo \"highlight\" shortcode features: - - Code blocks with line numbers (if the -n or +n switch is used) +Hugo \"highlight\" shortcode is needed if `org-hugo-goldmark' is +nil and, + - 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) + parameter is used). - Set the `linenos' argument to the value passed by :linenos - (defaults to `table') - -CONTENTS is nil. INFO is a plist used as a communication -channel." + (defaults to `table')." (let* ((lang (org-element-property :language src-block)) (parameters-str (org-element-property :parameters src-block)) (parameters (org-babel-parse-header-arguments parameters-str)) - (is-fm-extra (cdr (assoc :front_matter_extra parameters))) - (fm-format (plist-get info :hugo-front-matter-format))) + (is-fm-extra (cdr (assoc :front_matter_extra parameters)))) ;; (message "ox-hugo src [dbg] lang: %S" lang) - ;; (message "ox-hugo src [dbg] is-fm-extra: %S" is-fm-extra) ;; (message "ox-hugo src [dbg] parameters: %S" parameters) - (if (and is-fm-extra - (member lang '("toml" "yaml"))) - (progn - ;; The fm-extra src block lang and user-set fm-format have to - ;; be the same. Else. that src block is completely discarded. - (when (string= lang fm-format) - (let ((fm-extra (org-export-format-code-default src-block info))) - ;; (message "ox-hugo src [dbg] fm-extra: %S" fm-extra) - (plist-put info :fm-extra fm-extra))) - ;; Do not export the `:front_matter_extra' TOML/YAML source - ;; blocks in Markdown body. - nil) + ;; (message "ox-hugo src [dbg] is-fm-extra: %S" is-fm-extra) + + ;; Extra front matter. + (cond + ((and is-fm-extra + (member lang '("toml" "yaml"))) + (let ((fm-format (plist-get info :hugo-front-matter-format))) + ;; The fm-extra src block lang and user-set fm-format have to + ;; be the same. Else. that src block is completely discarded. + (when (string= lang fm-format) + (let ((fm-extra (org-export-format-code-default src-block info))) + ;; (message "ox-hugo src [dbg] fm-extra: %S" fm-extra) + (plist-put info :fm-extra fm-extra))) + ;; Do not export the `:front_matter_extra' TOML/YAML source + ;; blocks in Markdown body. + nil)) + + ;; Regular src block. + (t (let* (;; See `org-element-src-block-parser' for all SRC-BLOCK properties. (number-lines (org-element-property :number-lines src-block)) ;Non-nil if -n or +n switch is used - (hl-lines (cdr (assoc :hl_lines parameters))) (linenos-style (cdr (assoc :linenos parameters))) + (hl-lines (cdr (assoc :hl_lines parameters))) (hl-lines (cond ((stringp hl-lines) (replace-regexp-in-string "," " " hl-lines)) ;"1,3-4" -> "1 3-4" ((numberp hl-lines) (number-to-string hl-lines)))) + ;; Use the `highlight' shortcode if any of the line + ;; numbering or highlighting option is set or if + ;; HUGO_CODE_FENCE is nil. + (use-highlight-sc (or number-lines + hl-lines + linenos-style + (null (org-hugo--plist-get-true-p info :hugo-code-fence)))) (src-ref (org-blackfriday--get-reference src-block)) (src-anchor (if src-ref (format "\n" src-ref) @@ -2770,58 +2783,55 @@ channel." (format "%s %s" caption-prefix src-block-num)) caption-str)))) - content + (src-code (org-hugo--escape-hugo-shortcode + (org-export-format-code-default src-block info) + lang)) + code-attr-str + src-code-wrap ret) ;; (message "ox-hugo src [dbg] number-lines: %S" number-lines) ;; (message "ox-hugo src [dbg] parameters: %S" parameters) - (setq content - (cond - ;; If all: number-lines, hl-lines and linenos-style are nil - ;; , AND if :hugo-code-fence is non-nil (which is, by default). - ((and (null number-lines) - (null hl-lines) - (null linenos-style) - (org-hugo--plist-get-true-p info :hugo-code-fence)) - (let ((content1 (org-blackfriday-src-block src-block nil info))) - (setq content1 (org-hugo--escape-hugo-shortcode content1 lang)) - content1)) - ;; If number-lines is non-nil - ;; , or if hl-lines is non-nil - ;; , or if linenos-style is non-nil - ;; , or if :hugo-code-fence is nil - (t - (let ((code (org-export-format-code-default src-block info)) - (linenos-str "") - (hllines-str "") - ;; Formatter string where the first arg si linenos-str and - ;; second is hllines-str. - (highlight-args-str "%s%s")) - (when (or number-lines hl-lines linenos-style) - (setq highlight-args-str " \"%s%s\"")) - (when (or number-lines linenos-style) - (let ((linenos-style (or linenos-style "table"))) - (setq linenos-str (format "linenos=%s" linenos-style)) - (let ((linenostart-str (and ;Extract the start line number of the code block - (string-match "\\`\\s-*\\([0-9]+\\)\\s-\\{2\\}" code) - (match-string-no-properties 1 code)))) - (when linenostart-str - (setq linenos-str (format "%s, linenostart=%s" linenos-str linenostart-str))))) - ;; Remove Org-inserted numbers from the beginning of each - ;; line as the Hugo highlight shortcode will be used instead - ;; of literally inserting the line numbers. - (setq code (replace-regexp-in-string "^\\s-*[0-9]+\\s-\\{2\\}" "" code))) - (when hl-lines - (setq hllines-str (concat "hl_lines=" hl-lines)) - (when number-lines - (setq hllines-str (concat ", " hllines-str)))) - (setq code (org-hugo--escape-hugo-shortcode code lang)) - (format "{{< highlight %s%s >}}\n%s{{< /highlight >}}\n" - lang - (format highlight-args-str linenos-str hllines-str) - code))))) - (setq ret (concat src-anchor content caption-html)) - (setq ret (org-blackfriday--div-wrap-maybe src-block ret info)) - ret)))) + + (when (or linenos-style number-lines) + ;; Default "linenos" style set to "table" if linenos-style + ;; is nil. + (setq linenos-style (or linenos-style "table")) + (setq code-attr-str (format "linenos=%s" linenos-style)) + (let ((linenostart-str (and ;Extract the start line number of the src block + (string-match "\\`\\s-*\\([0-9]+\\)\\s-\\{2\\}" src-code) + (match-string-no-properties 1 src-code)))) + (when linenostart-str + (setq code-attr-str (format "%s, linenostart=%s" code-attr-str linenostart-str)))) + + (when number-lines + ;; Remove Org-inserted numbers from the beginning of each line + ;; as the Hugo highlight shortcode will be used instead of + ;; literally inserting the line numbers. + (setq src-code (replace-regexp-in-string "^\\s-*[0-9]+\\s-\\{2\\}" "" src-code)))) + + (when hl-lines + (if (org-string-nw-p code-attr-str) + (setq code-attr-str (format "%s, hl_lines=%s" code-attr-str hl-lines)) + (setq code-attr-str (format "hl_lines=%s" hl-lines)))) + + (unless use-highlight-sc + (plist-put info :md-code src-code) + (plist-put info :md-code-attr code-attr-str)) + + (setq src-code-wrap + (if use-highlight-sc + (let ((hl-attr (if (org-string-nw-p code-attr-str) + (format " \"%s\"" code-attr-str) + ""))) + (format "{{< highlight %s%s >}}\n%s{{< /highlight >}}\n" + lang hl-attr src-code)) + (org-blackfriday-src-block src-block nil info))) + + (setq ret (org-blackfriday--div-wrap-maybe + src-block + (concat src-anchor src-code-wrap caption-html) + info)) + ret))))) ;;;; Special Block (defun org-hugo-special-block (special-block contents info) From 6f543996b12577517758dbb18881f861acf52ed5 Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Tue, 4 Jan 2022 17:21:15 -0500 Subject: [PATCH 6/8] Minor optimization of example block export Use the `example-code` derived from `org-hugo-example-block` in `org-blackfriday-example-block` even when line numbers are not enabled, but fenced code blocks are enabled (`use-highlight-sc` == nil). It's not a ground breaking optimization.. just that a call to `org-export-format-code-default` will be skipped in `org-blackfriday-example-block`. --- ox-hugo.el | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/ox-hugo.el b/ox-hugo.el index 7f476686..576d2280 100644 --- a/ox-hugo.el +++ b/ox-hugo.el @@ -1758,10 +1758,12 @@ information." ;; Remove Org-inserted numbers from the beginning of each line ;; as the Hugo highlight shortcode will be used instead of ;; literally inserting the line numbers. - (setq example-code (replace-regexp-in-string "^[0-9]+\\s-\\{2\\}" "" example-code))) - (unless use-highlight-sc - (plist-put info :md-code example-code) - (plist-put info :md-code-attr code-attr-str))) + (setq example-code (replace-regexp-in-string "^[0-9]+\\s-\\{2\\}" "" example-code)))) + + (unless use-highlight-sc + (plist-put info :md-code example-code) + (plist-put info :md-code-attr code-attr-str)) + (if use-highlight-sc (setq ret (org-blackfriday--div-wrap-maybe example-block From 3bccbd856899537bb94a3be099f34aee99502eec Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Tue, 4 Jan 2022 17:33:11 -0500 Subject: [PATCH 7/8] Src blocks use code fence instead of `highlight` if Goldmark enabled Ref: - https://github.com/kaushalmodi/ox-hugo/pull/499 - https://github.com/kaushalmodi/ox-hugo/issues/305 This update also "fixes" https://github.com/kaushalmodi/ox-hugo/issues/161. The code fenced block don't have the same issue as the `highlight` shortcode does. As we now export line numbered code blocks as fenced code blocks by default and are moving away from the buggy `highlight` shortcode, we are bypassing issue https://github.com/kaushalmodi/ox-hugo/issues/161. If you don't like the change in behavior of src block exports in this commit, customize `org-hugo-goldmark`. See https://github.com/kaushalmodi/ox-hugo/discussions/485. --- ox-hugo.el | 41 +++-- test/site/content-org/all-posts.org | 149 ++++++++++++++---- .../content/posts/source-block-indented.md | 39 +++-- .../source-block-md-with-hugo-shortcodes.md | 4 +- ...rce-block-with-highlighting-blackfriday.md | 134 ++++++++++++++++ .../posts/source-block-with-highlighting.md | 25 +-- .../posts/source-block-with-line-numbers.md | 27 ++-- .../content/posts/verse-for-indentation.md | 8 +- 8 files changed, 333 insertions(+), 94 deletions(-) create mode 100644 test/site/content/posts/source-block-with-highlighting-blackfriday.md diff --git a/ox-hugo.el b/ox-hugo.el index 576d2280..6703af60 100644 --- a/ox-hugo.el +++ b/ox-hugo.el @@ -2748,19 +2748,33 @@ nil and, (let* (;; See `org-element-src-block-parser' for all SRC-BLOCK properties. (number-lines (org-element-property :number-lines src-block)) ;Non-nil if -n or +n switch is used (linenos-style (cdr (assoc :linenos parameters))) - (hl-lines (cdr (assoc :hl_lines parameters))) - (hl-lines (cond - ((stringp hl-lines) - (replace-regexp-in-string "," " " hl-lines)) ;"1,3-4" -> "1 3-4" - ((numberp hl-lines) - (number-to-string hl-lines)))) - ;; Use the `highlight' shortcode if any of the line - ;; numbering or highlighting option is set or if - ;; HUGO_CODE_FENCE is nil. - (use-highlight-sc (or number-lines - hl-lines - linenos-style - (null (org-hugo--plist-get-true-p info :hugo-code-fence)))) + ;; Convert `hl-lines' to string. If it's not a number, + ;; it's already a string, or nil. + (hl-lines (let* ((hl-lines-param (cdr (assoc :hl_lines parameters)))) + ;; (message "ox-hugo src [dbg] hl-lines-param: %S" hl-lines-param) + (if (numberp hl-lines-param) + (number-to-string hl-lines-param) + hl-lines-param))) + ;; 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)) + ;; "Blackfriday mode" is enabled and line numbering + ;; or highlighting is needed. + (and (or number-lines hl-lines linenos-style) + (not (org-hugo--plist-get-true-p info :hugo-goldmark))))) + (hl-lines (when (stringp hl-lines) + (if use-highlight-sc + (progn + ;; Syntax of hl_lines in `highlight' shortcode: + ;; {{< highlight emacs-lisp "hl_lines=1 3-5" >}} .. + (replace-regexp-in-string "," " " hl-lines)) ;"1,3-5" -> "1 3-5" + ;; Fenced code blocks + ;; Syntax of hl_lines in fenced code attributes: + ;; ```emacs-lisp { hl_lines=["1","3-5"] } .. + (format "[%s]" + (mapconcat + (lambda(el) (format "%S" el)) + (split-string hl-lines ",") ","))))) ;"1,3-5" -> "[\"1\",\"3-5\"]" (src-ref (org-blackfriday--get-reference src-block)) (src-anchor (if src-ref (format "\n" src-ref) @@ -2811,6 +2825,7 @@ nil and, ;; literally inserting the line numbers. (setq src-code (replace-regexp-in-string "^\\s-*[0-9]+\\s-\\{2\\}" "" src-code)))) + ;; (message "ox-hugo src [dbg] hl-lines: %S" hl-lines) (when hl-lines (if (org-string-nw-p code-attr-str) (setq code-attr-str (format "%s, hl_lines=%s" code-attr-str hl-lines)) diff --git a/test/site/content-org/all-posts.org b/test/site/content-org/all-posts.org index 5b469b0a..61d863cd 100644 --- a/test/site/content-org/all-posts.org +++ b/test/site/content-org/all-posts.org @@ -1315,10 +1315,11 @@ This code block once again contains no backticks: (message "Hello again x6") #+end_src ** Source block annotations :src_block:annotations: -*** Source blocks with line number annotation :linenum: -**** Source blocks with line number annotation (Goldmark) :goldmark: +*** Code fence annotation with Goldmark :goldmark: +**** Source blocks with line number annotation (Goldmark) :linenum: :PROPERTIES: :EXPORT_FILE_NAME: source-block-with-line-numbers +:EXPORT_HUGO_ALIASES: source-block-with-line-numbers-goldmark :END: - [[https://orgmode.org/manual/Literal-examples.html][Org reference]] ***** Cases @@ -1373,6 +1374,73 @@ This code block once again contains no backticks: (message "This is line 31") (message "This is line 32") #+end_src +**** Source blocks with highlighting (Goldmark) :syntax_highlighting: +:PROPERTIES: +:EXPORT_FILE_NAME: source-block-with-highlighting +:CUSTOM_ID: source-blocks-with-highlighting +:EXPORT_HUGO_ALIASES: source-block-with-highlighting-goldmark +:EXPORT_HUGO_GOLDMARK: t +:END: +***** Without line numbers +:PROPERTIES: +:CUSTOM_ID: source-blocks-with-highlighting-no-linenums +:END: +******* Org source +#+begin_src org :noweb yes +<> +#+end_src +******* Output +#+begin_src org :noweb yes :exports results :results output replace :eval yes +<> +#+end_src +Above highlighting might look weird as the highlighting spans the full +page/container width. This could be either called a bug in Hugo, or +the HTML limitation. + +A workaround is below.. *use line numbers too!*. +******* Highlighting only 1 line +******** Org source +#+begin_src org :noweb yes +<> +#+end_src +******** Output +#+begin_src org :noweb yes :exports results :results output replace :eval yes +<> +#+end_src +***** With line numbers *not* starting from 1 +:PROPERTIES: +:CUSTOM_ID: source-blocks-with-highlighting-with-linenums-not-starting-from-1 +:END: +With line numbers enabled, the highlighting is limited to the width of +the HTML table rows if the =linenos= option is set to =table= +(default). + +- Note 1 :: When using both, switches (like =-n=), and header args + (like =:hl_lines=), the _switches have to come first_. +- Note 2 :: The line numbers in the value for =:hl_lines= parameter is + always with the starting line number reference of 1. That + has no relation with the value of the line numbers + displayed using the =-n= or =+n= switches! +******* Org source +#+begin_src org :noweb yes +<> +#+end_src +******* Output +#+begin_src org :noweb yes :exports results :results output replace :eval yes +<> +#+end_src +***** With line numbers +:PROPERTIES: +:CUSTOM_ID: source-blocks-with-highlighting-with-linenums +:END: +******* Org source +#+begin_src org :noweb yes +<> +#+end_src +******* Output +#+begin_src org :noweb yes :exports results :results output replace :eval yes +<> +#+end_src ** Highlight Shortcode :highlight:shortcode: *** Source blocks with =highlight= shortcode :PROPERTIES: @@ -1388,54 +1456,57 @@ property needs to be left *empty* instead of setting to =nil=! :END: #+end_example #+include: "./all-posts.org::#example-text-with-code-blocks" :only-contents t -*** Source blocks with line number annotation (Blackfriday) :blackfriday:linenum: +*** Annotate code blocks need =highlight= shortcode in Blackfriday :blackfriday: :PROPERTIES: -:EXPORT_FILE_NAME: source-block-with-line-numbers-blackfriday :EXPORT_HUGO_GOLDMARK: :END: +**** Source blocks with line number annotation (Blackfriday) :linenum: +:PROPERTIES: +:EXPORT_FILE_NAME: source-block-with-line-numbers-blackfriday +:END: - [[https://orgmode.org/manual/Literal-examples.html][Org reference]] - [[https://gohugo.io/content-management/syntax-highlighting/][Hugo =highlight= shortcode with line numbers]] -**** Cases +***** Cases :PROPERTIES: :CUSTOM_ID: source-block-line-number-cases :END: -***** Default new line number start -****** Org source +****** Default new line number start +******* Org source #+begin_src org :noweb yes <> #+end_src -****** Output +******* Output #+begin_src org :noweb yes :exports results :results output replace :eval yes <> #+end_src -***** Specify new line number start -****** Org source +****** Specify new line number start +******* Org source #+begin_src org :noweb yes <> #+end_src -****** Output +******* Output #+begin_src org :noweb yes :exports results :results output replace :eval yes <> #+end_src -***** Default continued line numbers -****** Org source +****** Default continued line numbers +******* Org source #+begin_src org :noweb yes <> #+end_src -****** Output +******* Output #+begin_src org :noweb yes :exports results :results output replace :eval yes <> #+end_src -***** Specify continued line numbers jump -****** Org source +****** Specify continued line numbers jump +******* Org source #+begin_src org :noweb yes <> #+end_src -****** Output +******* Output #+begin_src org :noweb yes :exports results :results output replace :eval yes <> #+end_src -**** Specifying ~linenos~ parameter +***** Specifying ~linenos~ parameter #+begin_src emacs-lisp :linenos false (message "This is line 1") (message "This is line 2") @@ -1447,20 +1518,19 @@ property needs to be left *empty* instead of setting to =nil=! (message "This is line 31") (message "This is line 32") #+end_src -*** Source blocks with highlighting +**** Source blocks with highlighting (Blackfriday) :syntax_highlighting: :PROPERTIES: -:EXPORT_FILE_NAME: source-block-with-highlighting -:CUSTOM_ID: source-blocks-with-highlighting +:EXPORT_FILE_NAME: source-block-with-highlighting-blackfriday :END: -**** Without line numbers +***** Without line numbers :PROPERTIES: :CUSTOM_ID: source-blocks-with-highlighting-no-linenums :END: -****** Org source +******* Org source #+begin_src org :noweb yes <> #+end_src -****** Output +******* Output #+begin_src org :noweb yes :exports results :results output replace :eval yes <> #+end_src @@ -1469,16 +1539,16 @@ page/container width. This could be either called a bug in Hugo, or the HTML limitation. A workaround is below.. *use line numbers too!*. -****** Highlighting only 1 line -******* Org source +******* Highlighting only 1 line +******** Org source #+begin_src org :noweb yes <> #+end_src -******* Output +******** Output #+begin_src org :noweb yes :exports results :results output replace :eval yes <> #+end_src -**** With line numbers *not* starting from 1 +***** With line numbers *not* starting from 1 :PROPERTIES: :CUSTOM_ID: source-blocks-with-highlighting-with-linenums-not-starting-from-1 :END: @@ -1492,23 +1562,23 @@ in the =highlight= shortcode when line numbers are enabled). always with the starting line number reference of 1. That has no relation with the value of the line numbers displayed using the =-n= or =+n= switches! -****** Org source +******* Org source #+begin_src org :noweb yes <> #+end_src -****** Output +******* Output #+begin_src org :noweb yes :exports results :results output replace :eval yes <> #+end_src -**** With line numbers +***** With line numbers :PROPERTIES: :CUSTOM_ID: source-blocks-with-highlighting-with-linenums :END: -****** Org source +******* Org source #+begin_src org :noweb yes <> #+end_src -****** Output +******* Output #+begin_src org :noweb yes :exports results :results output replace :eval yes <> #+end_src @@ -1700,9 +1770,10 @@ YZ0 #+end_example Above results block will be in _green_ text. -** Indented source block :indented:lists:code_fence:highlight:src_block:@upstream: +** Indented source block :indented:lists:code_fence:src_block: :PROPERTIES: :EXPORT_FILE_NAME: source-block-indented +:EXPORT_HUGO_GOLDMARK: t :END: #+begin_description Test that indented source blocks, and also the ones in lists export @@ -1749,7 +1820,15 @@ Reference: {{{hugoissue(4006)}}} *** Code blocks in list using ~highlight~ shortcode Reference: {{{hugoissue(4717)}}}, {{{oxhugoissue(161)}}} -This is an *upstream* bug in ~hugo~ as of 2018-05-12. The issues is +#+html: +#+attr_html: :class red +#+begin_note +Switched from exporting the ~highlight~ shortcode to exporting the +code fenced blocks with attributes. These code fences are support by +Hugo + Goldmark since v0.60.0. +#+end_note + +This is an *upstream* bug in ~hugo~ as of 2018-05-12. The issue is that when the code blocks in ~highlight~ shortcodes are inserted at the required indentation levels in lists.. so that they get rendered *in* the list at *that* indentation level, those indentations are not diff --git a/test/site/content/posts/source-block-indented.md b/test/site/content/posts/source-block-indented.md index 339f73bb..70509610 100644 --- a/test/site/content/posts/source-block-indented.md +++ b/test/site/content/posts/source-block-indented.md @@ -4,8 +4,7 @@ description = """ Test that indented source blocks, and also the ones in lists export fine. """ -tags = ["indented", "lists", "code-fence", "highlight", "src-block"] -categories = ["upstream"] +tags = ["indented", "lists", "code-fence", "src-block"] draft = false +++ @@ -64,7 +63,17 @@ Reference: `hugo` Issue #[4006](https://github.com/gohugoio/hugo/issues/4006) Reference: `hugo` Issue #[4717](https://github.com/gohugoio/hugo/issues/4717), `ox-hugo` Issue #[161](https://github.com/kaushalmodi/ox-hugo/issues/161) -This is an **upstream** bug in `hugo` as of 2018-05-12. The issues is + + +
+ +Switched from exporting the `highlight` shortcode to exporting the +code fenced blocks with attributes. These code fences are support by +Hugo + Goldmark since v0.60.0. + +
+ +This is an **upstream** bug in `hugo` as of 2018-05-12. The issue is that when the code blocks in `highlight` shortcodes are inserted at the required indentation levels in lists.. so that they get rendered **in** the list at **that** indentation level, those indentations are not @@ -80,34 +89,34 @@ there. - List item 1 - {{< highlight emacs-lisp "linenos=table, linenostart=1" >}} + ```emacs-lisp { linenos=table, linenostart=1 } (message "I am in list at level-1 indentation") - {{< /highlight >}} + ``` - List item 1.1 - {{< highlight emacs-lisp "linenos=table, linenostart=1" >}} + ```emacs-lisp { linenos=table, linenostart=1 } (message "I am in list at level-2 indentation") - {{< /highlight >}} + ``` - List item 1.1.1 - {{< highlight emacs-lisp "linenos=table, linenostart=1" >}} + ```emacs-lisp { linenos=table, linenostart=1 } (message "I am in list at level-3 indentation") - {{< /highlight >}} + ``` - List item 2.1 - {{< highlight emacs-lisp "linenos=table, linenostart=1" >}} + ```emacs-lisp { linenos=table, linenostart=1 } (message "I am in list back at level-2 indentation") - {{< /highlight >}} + ``` - List item 2 - {{< highlight emacs-lisp "linenos=table, linenostart=1" >}} + ```emacs-lisp { linenos=table, linenostart=1 } (message "I am in list back at level-1 indentation") - {{< /highlight >}} + ``` -{{< highlight emacs-lisp "linenos=table, linenostart=1" >}} +```emacs-lisp { linenos=table, linenostart=1 } (message "And now I am at level-0 indentation") -{{< /highlight >}} +``` diff --git a/test/site/content/posts/source-block-md-with-hugo-shortcodes.md b/test/site/content/posts/source-block-md-with-hugo-shortcodes.md index 4a5812cf..edfe9905 100644 --- a/test/site/content/posts/source-block-md-with-hugo-shortcodes.md +++ b/test/site/content/posts/source-block-md-with-hugo-shortcodes.md @@ -26,10 +26,10 @@ should **not** be expanded.. they should be visible verbatim. Here, the `-n` switch is added to the Org source block to auto-enable[^fn:1] using the `highlight` shortcode. -{{< highlight md "linenos=table, linenostart=1" >}} +```md { linenos=table, linenostart=1 } {{}} {{%/* figure src="https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png" */%}} -{{< /highlight >}} +``` ## Shortcodes **not** escaped {#shortcodes-not-escaped} diff --git a/test/site/content/posts/source-block-with-highlighting-blackfriday.md b/test/site/content/posts/source-block-with-highlighting-blackfriday.md new file mode 100644 index 00000000..558661f3 --- /dev/null +++ b/test/site/content/posts/source-block-with-highlighting-blackfriday.md @@ -0,0 +1,134 @@ ++++ +title = "Source blocks with highlighting (Blackfriday)" +tags = ["src-block", "highlight", "shortcode", "blackfriday", "syntax-highlighting"] +draft = false ++++ + +## Without line numbers {#source-blocks-with-highlighting-no-linenums} + + +#### Org source {#org-source} + +```org +#+begin_src emacs-lisp :hl_lines 1,3-5 +(message "This is line 1") +(message "This is line 2") +(message "This is line 3") +(message "This is line 4") +(message "This is line 5") +(message "This is line 6") +#+end_src +``` + + +#### Output {#output} + +{{< highlight emacs-lisp "hl_lines=1 3-5" >}} +(message "This is line 1") +(message "This is line 2") +(message "This is line 3") +(message "This is line 4") +(message "This is line 5") +(message "This is line 6") +{{< /highlight >}} + +Above highlighting might look weird as the highlighting spans the full +page/container width. This could be either called a bug in Hugo, or +the HTML limitation. + +A workaround is below.. **use line numbers too!**. + + +#### Highlighting only 1 line {#highlighting-only-1-line} + + +##### Org source {#org-source} + +```org +#+begin_src emacs-lisp :hl_lines 2 +(message "This is line 1") +(message "This is line 2") +(message "This is line 3") +#+end_src +``` + + +##### Output {#output} + +{{< highlight emacs-lisp "hl_lines=2" >}} +(message "This is line 1") +(message "This is line 2") +(message "This is line 3") +{{< /highlight >}} + + +## With line numbers **not** starting from 1 {#source-blocks-with-highlighting-with-linenums-not-starting-from-1} + +With line numbers enabled, the highlighting is limited to the width of +the HTML table rows (because `ox-hugo` sets the `linenos=table` option +in the `highlight` shortcode when line numbers are enabled). + +Note 1 +: When using both, switches (like `-n`), and header args + (like `:hl_lines`), the switches have to come first. + +Note 2 +: The line numbers in the value for `:hl_lines` parameter is + always with the starting line number reference of 1. That + has no relation with the value of the line numbers + displayed using the `-n` or `+n` switches! + + +#### Org source {#org-source} + +```org +#+begin_src emacs-lisp -n 7 :hl_lines 1,3-5 +(message "This is line 7 in code, but line 1 for highlighting reference") +(message "This is line 8 in code, but line 2 for highlighting reference") +(message "This is line 9 in code, but line 3 for highlighting reference") +(message "This is line 10 in code, but line 4 for highlighting reference") +(message "This is line 11 in code, but line 5 for highlighting reference") +(message "This is line 12 in code, but line 6 for highlighting reference") +#+end_src +``` + + +#### Output {#output} + +{{< highlight emacs-lisp "linenos=table, linenostart=7, hl_lines=1 3-5" >}} +(message "This is line 7 in code, but line 1 for highlighting reference") +(message "This is line 8 in code, but line 2 for highlighting reference") +(message "This is line 9 in code, but line 3 for highlighting reference") +(message "This is line 10 in code, but line 4 for highlighting reference") +(message "This is line 11 in code, but line 5 for highlighting reference") +(message "This is line 12 in code, but line 6 for highlighting reference") +{{< /highlight >}} + + +## With line numbers {#source-blocks-with-highlighting-with-linenums} + + +#### Org source {#org-source} + +```org +#+begin_src emacs-lisp -n :hl_lines 1,3-5 +(message "This is line 1") +(message "This is line 2") +(message "This is line 3") +(message "This is line 4") +(message "This is line 5") +(message "This is line 6") +#+end_src +``` + + +#### Output {#output} + +{{< highlight emacs-lisp "linenos=table, linenostart=1, hl_lines=1 3-5" >}} +(message "This is line 1") +(message "This is line 2") +(message "This is line 3") +(message "This is line 4") +(message "This is line 5") +(message "This is line 6") +{{< /highlight >}} diff --git a/test/site/content/posts/source-block-with-highlighting.md b/test/site/content/posts/source-block-with-highlighting.md index 6bf7ec07..e729e74c 100644 --- a/test/site/content/posts/source-block-with-highlighting.md +++ b/test/site/content/posts/source-block-with-highlighting.md @@ -1,6 +1,7 @@ +++ -title = "Source blocks with highlighting" -tags = ["src-block", "highlight", "shortcode"] +title = "Source blocks with highlighting (Goldmark)" +aliases = ["/posts/source-block-with-highlighting-goldmark"] +tags = ["src-block", "annotations", "goldmark", "syntax-highlighting"] draft = false +++ @@ -23,14 +24,14 @@ draft = false #### Output {#output} -{{< highlight emacs-lisp "hl_lines=1 3-5" >}} +```emacs-lisp { hl_lines=["1","3-5"] } (message "This is line 1") (message "This is line 2") (message "This is line 3") (message "This is line 4") (message "This is line 5") (message "This is line 6") -{{< /highlight >}} +``` Above highlighting might look weird as the highlighting spans the full page/container width. This could be either called a bug in Hugo, or @@ -55,18 +56,18 @@ A workaround is below.. **use line numbers too!**. ##### Output {#output} -{{< highlight emacs-lisp "hl_lines=2" >}} +```emacs-lisp { hl_lines=["2"] } (message "This is line 1") (message "This is line 2") (message "This is line 3") -{{< /highlight >}} +``` ## With line numbers **not** starting from 1 {#source-blocks-with-highlighting-with-linenums-not-starting-from-1} With line numbers enabled, the highlighting is limited to the width of -the HTML table rows (because `ox-hugo` sets the `linenos=table` option -in the `highlight` shortcode when line numbers are enabled). +the HTML table rows if the `linenos` option is set to `table` +(default). Note 1 : When using both, switches (like `-n`), and header args @@ -95,14 +96,14 @@ Note 2 #### Output {#output} -{{< highlight emacs-lisp "linenos=table, linenostart=7, hl_lines=1 3-5" >}} +```emacs-lisp { linenos=table, linenostart=7, hl_lines=["1","3-5"] } (message "This is line 7 in code, but line 1 for highlighting reference") (message "This is line 8 in code, but line 2 for highlighting reference") (message "This is line 9 in code, but line 3 for highlighting reference") (message "This is line 10 in code, but line 4 for highlighting reference") (message "This is line 11 in code, but line 5 for highlighting reference") (message "This is line 12 in code, but line 6 for highlighting reference") -{{< /highlight >}} +``` ## With line numbers {#source-blocks-with-highlighting-with-linenums} @@ -124,11 +125,11 @@ Note 2 #### Output {#output} -{{< highlight emacs-lisp "linenos=table, linenostart=1, hl_lines=1 3-5" >}} +```emacs-lisp { linenos=table, linenostart=1, hl_lines=["1","3-5"] } (message "This is line 1") (message "This is line 2") (message "This is line 3") (message "This is line 4") (message "This is line 5") (message "This is line 6") -{{< /highlight >}} +``` diff --git a/test/site/content/posts/source-block-with-line-numbers.md b/test/site/content/posts/source-block-with-line-numbers.md index 5d0f0ece..d3b2a0e6 100644 --- a/test/site/content/posts/source-block-with-line-numbers.md +++ b/test/site/content/posts/source-block-with-line-numbers.md @@ -1,6 +1,7 @@ +++ title = "Source blocks with line number annotation (Goldmark)" -tags = ["src-block", "annotations", "linenum", "goldmark"] +aliases = ["/posts/source-block-with-line-numbers-goldmark"] +tags = ["src-block", "annotations", "goldmark", "linenum"] draft = false +++ @@ -25,10 +26,10 @@ draft = false #### Output {#output} -{{< highlight emacs-lisp "linenos=table, linenostart=1" >}} +```emacs-lisp { linenos=table, linenostart=1 } ;; this will export with line number 1 (default) (message "This is line 2") -{{< /highlight >}} +``` ### Specify new line number start {#specify-new-line-number-start} @@ -46,10 +47,10 @@ draft = false #### Output {#output} -{{< highlight emacs-lisp "linenos=table, linenostart=20" >}} +```emacs-lisp { linenos=table, linenostart=20 } ;; this will export with line number 20 (message "This is line 21") -{{< /highlight >}} +``` ### Default continued line numbers {#default-continued-line-numbers} @@ -67,10 +68,10 @@ draft = false #### Output {#output} -{{< highlight emacs-lisp "linenos=table, linenostart=22" >}} +```emacs-lisp { linenos=table, linenostart=22 } ;; This will be listed as line 22 (message "This is line 23") -{{< /highlight >}} +``` ### Specify continued line numbers jump {#specify-continued-line-numbers-jump} @@ -88,22 +89,22 @@ draft = false #### Output {#output} -{{< highlight emacs-lisp "linenos=table, linenostart=33" >}} +```emacs-lisp { linenos=table, linenostart=33 } ;; This will be listed as line 33 (message "This is line 34") -{{< /highlight >}} +``` ## Specifying `linenos` parameter {#specifying-linenos-parameter} -{{< highlight emacs-lisp "linenos=false" >}} +```emacs-lisp { linenos=false } (message "This is line 1") (message "This is line 2") (message "This is line 3") -{{< /highlight >}} +``` -{{< highlight emacs-lisp "linenos=inline, linenostart=30" >}} +```emacs-lisp { linenos=inline, linenostart=30 } (message "This is line 30") (message "This is line 31") (message "This is line 32") -{{< /highlight >}} +``` diff --git a/test/site/content/posts/verse-for-indentation.md b/test/site/content/posts/verse-for-indentation.md index 1787e59e..4b74a3df 100644 --- a/test/site/content/posts/verse-for-indentation.md +++ b/test/site/content/posts/verse-for-indentation.md @@ -46,7 +46,7 @@ removed when translating to Markdown. ## Corner cases {#corner-cases} -{{< highlight org "linenos=table, linenostart=0" >}} +```org { linenos=table, linenostart=0 } #+begin_verse >Line 1 above was empty. So the first =>= seen on this line is removed. @@ -54,7 +54,7 @@ Line 3 had no =>= char. > ← See that this =>= on line 4 is retained even at the beginning of the line. Line 5 has this > charcter in-between and is retained. #+end_verse -{{< /highlight >}} +``` Only the **first** `>` character immediately following spaces and empty lines will be removed: @@ -72,7 +72,7 @@ in the final output, they can use `>>` instead.. **only for that first instance**. The below Verse block is same as above except that the first `>` is retained in the final output. -{{< highlight org "linenos=table, linenostart=0" >}} +```org { linenos=table, linenostart=0 } #+begin_verse >>Line 1 above was empty. So *only* the first =>= seen on this line is removed. @@ -80,7 +80,7 @@ Line 3 had no =>= char. > ← See that this =>= on line 4 is retained even at the beginning of the line. Line 5 has this > charcter in-between and is retained. #+end_verse -{{< /highlight >}} +```


From 6f04f2092338a7f11c2cb9eae0a0bf1a89996fa7 Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Tue, 4 Jan 2022 19:11:02 -0500 Subject: [PATCH 8/8] Update references to the `highlight` shortcode in manual and tests --- doc/ox-hugo-manual.org | 118 +++++++++++------- test/site/content-org/all-posts.org | 47 ++----- .../posts/example-block-with-line-numbers.md | 4 +- .../content/posts/source-block-indented.md | 8 ++ .../source-block-md-with-hugo-shortcodes.md | 13 +- ...rce-block-with-highlighting-blackfriday.md | 22 +--- .../posts/source-block-with-highlighting.md | 2 +- ...rce-block-with-line-numbers-blackfriday.md | 2 +- 8 files changed, 104 insertions(+), 112 deletions(-) diff --git a/doc/ox-hugo-manual.org b/doc/ox-hugo-manual.org index 414f6061..0acd29ad 100644 --- a/doc/ox-hugo-manual.org +++ b/doc/ox-hugo-manual.org @@ -1327,11 +1327,19 @@ adding this to the CSS: 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 set to a non-nil -value. So the code blocks will be exported with GitHub-style -code-fencing with triple-backticks when possible. +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. -Example: +For example, below Org source block: + +#+begin_src org +,#+begin_src emacs-lisp +(message "Hello") +,#+end_src +#+end_src + +will export to: #+begin_src md ```emacs-lisp @@ -1344,17 +1352,8 @@ Example: least as of [[https://github.com/gohugoio/hugo/commit/bfb9613a14ab2d93a4474e5486d22e52a9d5e2b3][Hugo v0.60.0]]) for syntax highlighting to work for fenced code blocks. -The Hugo =highlight= shortcode is automatically used instead of code -fences (even with this property at a non-nil value) if: -- Line numbers are enabled using the Org =-n= / =+n= syntax (see - below), or -- Line highlighting is enabled using the =:hl_lines= parameter in the - source block header (see below), or -- =:linenos= parameter is specified in the source block header (see - below). - -Set the =HUGO_CODE_FENCE= property to =nil= if you want to *always* -use the Hugo =highlight= shortcode. +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 @@ -1364,37 +1363,10 @@ Here are some examples fetched from the "Source blocks with line number annotation" test case in the {{{ox-hugo-test-file}}}. #+include: "../test/site/content-org/all-posts.org::#source-block-line-number-cases" :only-contents t -**** Highlighting -Implementing this feature was interesting, because while Org doesn't -have a syntax to enable highlighting only specific lines, the Hugo -=highlight= shortcode does allow that via =hl_lines= argument. - -So the challenge was to present that "lines to be highlighted" -information in the Org source in a nice format and then translate that -to the =hl_lines= =highlight= shortcode argument at the time of -exporting. - -It involved /hacking/ the =org-babel-exp-code=. See [[https://lists.gnu.org/archive/html/emacs-orgmode/2017-10/msg00300.html][this discussion on -the =emacs-orgmode= thread]] if interested. - -This feature is implemented by using a parameter called =:hl_lines= in -the header of source blocks. This parameter is specific to =ox-hugo=, -and that's why implementing this needed that hack. - -If a user wants to highlight lines 1, and then 3 to 5, they would add -=:hl_lines 1,3-5= to the source block header. -# Below 2 include statements fetch the noweb references used in the -# code inserted by the following include statements. -#+include: "../test/site/content-org/all-posts.org::#source-block-with-line-numbers-examples" -#+include: "../test/site/content-org/all-posts.org::#source-block-with-line-highlighting-examples" -***** Without line numbers -#+include: "../test/site/content-org/all-posts.org::#source-blocks-with-highlighting-no-linenums" :only-contents t -***** With line numbers -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 -**** Line number Style (*linenos*) +***** Line number Style (*linenos*) +:PROPERTIES: +:CUSTOM_ID: linenos +:END: When line numbers are enabled, by default the "table" style is used for line numbers. This is specified using the [[https://gohugo.io/content-management/syntax-highlighting/#highlight-shortcode][=linenos= argument to the =highlight= shortcode]]. @@ -1421,7 +1393,61 @@ by adding =:linenos false= to their headers. ,#+end_src #+end_src +- Valid values of ~linenos~ :: ~table~ (default), ~true~, ~false~, + ~inline~ + /The same =:linenos= header arg works for example blocks too./ +**** Highlighting +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. + +So the challenge was to present that "lines to be highlighted" +information in the Org source in a nice format and then translate that +to the =hl_lines= attribute with the required format at the time of +exporting. + +It involved /hacking/ the =org-babel-exp-code=. See [[https://lists.gnu.org/archive/html/emacs-orgmode/2017-10/msg00300.html][this discussion on +the =emacs-orgmode= thread]] if interested. + +This feature is implemented by using a parameter called =:hl_lines= in +the header of source blocks. This parameter is specific to =ox-hugo=, +and that's why implementing this needed that hack. + +If a user wants to highlight lines 1, and then 3 to 5, they would add +=:hl_lines 1,3-5= to the source block header. +***** Noweb refences :noexport: +Below 2 include statements fetch the noweb references used in the code +inserted by other include statements in the following sections. + +They are included to get the /noweb/ references working but they do +not need to be exported. + +#+include: "../test/site/content-org/all-posts.org::#source-block-with-line-numbers-examples" +#+include: "../test/site/content-org/all-posts.org::#source-block-with-line-highlighting-examples" +***** Highlighting without line numbers +#+include: "../test/site/content-org/all-posts.org::#source-blocks-with-highlighting-no-linenums" :only-contents t +***** Highlighting with line numbers +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: diff --git a/test/site/content-org/all-posts.org b/test/site/content-org/all-posts.org index 61d863cd..bd1f3a82 100644 --- a/test/site/content-org/all-posts.org +++ b/test/site/content-org/all-posts.org @@ -1374,7 +1374,7 @@ This code block once again contains no backticks: (message "This is line 31") (message "This is line 32") #+end_src -**** Source blocks with highlighting (Goldmark) :syntax_highlighting: +**** Source blocks with highlighting (Goldmark) :highlight: :PROPERTIES: :EXPORT_FILE_NAME: source-block-with-highlighting :CUSTOM_ID: source-blocks-with-highlighting @@ -1467,9 +1467,6 @@ property needs to be left *empty* instead of setting to =nil=! - [[https://orgmode.org/manual/Literal-examples.html][Org reference]] - [[https://gohugo.io/content-management/syntax-highlighting/][Hugo =highlight= shortcode with line numbers]] ***** Cases -:PROPERTIES: -:CUSTOM_ID: source-block-line-number-cases -:END: ****** Default new line number start ******* Org source #+begin_src org :noweb yes @@ -1518,14 +1515,11 @@ property needs to be left *empty* instead of setting to =nil=! (message "This is line 31") (message "This is line 32") #+end_src -**** Source blocks with highlighting (Blackfriday) :syntax_highlighting: +**** Source blocks with highlighting (Blackfriday) :highlight: :PROPERTIES: :EXPORT_FILE_NAME: source-block-with-highlighting-blackfriday :END: ***** Without line numbers -:PROPERTIES: -:CUSTOM_ID: source-blocks-with-highlighting-no-linenums -:END: ******* Org source #+begin_src org :noweb yes <> @@ -1549,19 +1543,6 @@ A workaround is below.. *use line numbers too!*. <> #+end_src ***** With line numbers *not* starting from 1 -:PROPERTIES: -:CUSTOM_ID: source-blocks-with-highlighting-with-linenums-not-starting-from-1 -:END: -With line numbers enabled, the highlighting is limited to the width of -the HTML table rows (because =ox-hugo= sets the =linenos=table= option -in the =highlight= shortcode when line numbers are enabled). - -- Note 1 :: When using both, switches (like =-n=), and header args - (like =:hl_lines=), the _switches have to come first_. -- Note 2 :: The line numbers in the value for =:hl_lines= parameter is - always with the starting line number reference of 1. That - has no relation with the value of the line numbers - displayed using the =-n= or =+n= switches! ******* Org source #+begin_src org :noweb yes <> @@ -1571,9 +1552,6 @@ in the =highlight= shortcode when line numbers are enabled). <> #+end_src ***** With line numbers -:PROPERTIES: -:CUSTOM_ID: source-blocks-with-highlighting-with-linenums -:END: ******* Org source #+begin_src org :noweb yes <> @@ -1826,8 +1804,12 @@ Reference: {{{hugoissue(4717)}}}, {{{oxhugoissue(161)}}} Switched from exporting the ~highlight~ shortcode to exporting the code fenced blocks with attributes. These code fences are support by Hugo + Goldmark since v0.60.0. + +*Below notes are now outdated and thus grayed out.* #+end_note +#+html: +#+begin_gray This is an *upstream* bug in ~hugo~ as of 2018-05-12. The issue is that when the code blocks in ~highlight~ shortcodes are inserted at the required indentation levels in lists.. so that they get rendered @@ -1841,6 +1823,7 @@ unremoved indentation on the last line of those code blocks. In the above section, the same code blocks are code-fenced instead of using ~highlight~ shortcode, and the extra indentation is not seen there. +#+end_gray - List item 1 #+begin_src emacs-lisp -n @@ -1882,9 +1865,9 @@ should *not* be expanded.. they should be visible verbatim. {{< figure src="https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png" >}} {{% figure src="https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png" %}} #+end_src -**** Code block using =highlight= shortcode -Here, the =-n= switch is added to the Org source block to -auto-enable[fn:4] using the =highlight= shortcode. +**** Code block using code fences with line numbering enabled +Here, the =-n= switch is added to the Org source block to enable line +numbering. #+begin_src md -n {{< figure src="https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png" >}} {{% figure src="https://ox-hugo.scripter.co/test/images/org-mode-unicorn-logo.png" %}} @@ -2049,7 +2032,6 @@ This is an example :EXPORT_FILE_NAME: example-block-with-line-numbers :END: - [[https://orgmode.org/manual/Literal-examples.html][Org reference]] -- [[https://gohugo.io/content-management/syntax-highlighting/][Hugo =highlight= shortcode with line numbers]] *** Default new line number start #+begin_example -n line 1 @@ -2078,6 +2060,8 @@ line 33 line 34 #+end_example *** Specifying ~linenos~ parameter +In the below block, ~:linenos false~ switch was added to the example +block header. #+begin_example :linenos false This is line 1 This is line 2 @@ -8202,13 +8186,6 @@ and /mark.js/. -- [[https://gist.github.com/eddiewebb/735feb48f50f0ddd65ae5606a1 [fn:5] See [@thompson2016]. -[fn:4] Even if the user has set the =HUGO_CODE_FENCE= value to =t= -(via variable, keyword or subtree property), the Hugo =highlight= -shortcode will be used automatically instead of code fences if either -(i) the user has chosen to either show the line numbers, or (ii) has -chosen to highlight lines of code (See the =ox-hugo= documentation on -{{{doc(source-blocks,Source Blocks)}}}). - [fn:3] This is a long footnote. It is so long that it gets auto-filled over multiple lines. But even then it should be handled fine. diff --git a/test/site/content/posts/example-block-with-line-numbers.md b/test/site/content/posts/example-block-with-line-numbers.md index 490fb299..fbe65eb6 100644 --- a/test/site/content/posts/example-block-with-line-numbers.md +++ b/test/site/content/posts/example-block-with-line-numbers.md @@ -5,7 +5,6 @@ draft = false +++ - [Org reference](https://orgmode.org/manual/Literal-examples.html) -- [Hugo `highlight` shortcode with line numbers](https://gohugo.io/content-management/syntax-highlighting/) ## Default new line number start {#default-new-line-number-start} @@ -49,6 +48,9 @@ line 34 ## Specifying `linenos` parameter {#specifying-linenos-parameter} +In the below block, `:linenos false` switch was added to the example +block header. + ```text { linenos=false } This is line 1 This is line 2 diff --git a/test/site/content/posts/source-block-indented.md b/test/site/content/posts/source-block-indented.md index 70509610..b0463999 100644 --- a/test/site/content/posts/source-block-indented.md +++ b/test/site/content/posts/source-block-indented.md @@ -71,8 +71,14 @@ Switched from exporting the `highlight` shortcode to exporting the code fenced blocks with attributes. These code fences are support by Hugo + Goldmark since v0.60.0. +**Below notes are now outdated and thus grayed out.** + + + +

+ This is an **upstream** bug in `hugo` as of 2018-05-12. The issue is that when the code blocks in `highlight` shortcodes are inserted at the required indentation levels in lists.. so that they get rendered @@ -87,6 +93,8 @@ In the above section, the same code blocks are code-fenced instead of using `highlight` shortcode, and the extra indentation is not seen there. +
+ - List item 1 ```emacs-lisp { linenos=table, linenostart=1 } diff --git a/test/site/content/posts/source-block-md-with-hugo-shortcodes.md b/test/site/content/posts/source-block-md-with-hugo-shortcodes.md index edfe9905..04b4f5fd 100644 --- a/test/site/content/posts/source-block-md-with-hugo-shortcodes.md +++ b/test/site/content/posts/source-block-md-with-hugo-shortcodes.md @@ -21,10 +21,10 @@ should **not** be expanded.. they should be visible verbatim. ``` -### Code block using `highlight` shortcode {#code-block-using-highlight-shortcode} +### Code block using code fences with line numbering enabled {#code-block-using-code-fences-with-line-numbering-enabled} -Here, the `-n` switch is added to the Org source block to -auto-enable[^fn:1] using the `highlight` shortcode. +Here, the `-n` switch is added to the Org source block to enable line +numbering. ```md { linenos=table, linenostart=1 } {{}} @@ -64,10 +64,3 @@ Note **It is necessary to set the Hugo site config variable `markup.highlight.codeFences` to `true` (default) for syntax highlighting to work for fenced code blocks.** - -[^fn:1]: Even if the user has set the `HUGO_CODE_FENCE` value to `t` - (via variable, keyword or subtree property), the Hugo `highlight` - shortcode will be used automatically instead of code fences if either - (i) the user has chosen to either show the line numbers, or (ii) has - chosen to highlight lines of code (See the `ox-hugo` documentation on - [Source Blocks](https://ox-hugo.scripter.co/doc/source-blocks)). diff --git a/test/site/content/posts/source-block-with-highlighting-blackfriday.md b/test/site/content/posts/source-block-with-highlighting-blackfriday.md index 558661f3..d6da6841 100644 --- a/test/site/content/posts/source-block-with-highlighting-blackfriday.md +++ b/test/site/content/posts/source-block-with-highlighting-blackfriday.md @@ -1,10 +1,10 @@ +++ title = "Source blocks with highlighting (Blackfriday)" -tags = ["src-block", "highlight", "shortcode", "blackfriday", "syntax-highlighting"] +tags = ["src-block", "shortcode", "blackfriday", "highlight"] draft = false +++ -## Without line numbers {#source-blocks-with-highlighting-no-linenums} +## Without line numbers {#without-line-numbers} #### Org source {#org-source} @@ -62,21 +62,7 @@ A workaround is below.. **use line numbers too!**. {{< /highlight >}} -## With line numbers **not** starting from 1 {#source-blocks-with-highlighting-with-linenums-not-starting-from-1} - -With line numbers enabled, the highlighting is limited to the width of -the HTML table rows (because `ox-hugo` sets the `linenos=table` option -in the `highlight` shortcode when line numbers are enabled). - -Note 1 -: When using both, switches (like `-n`), and header args - (like `:hl_lines`), the switches have to come first. - -Note 2 -: The line numbers in the value for `:hl_lines` parameter is - always with the starting line number reference of 1. That - has no relation with the value of the line numbers - displayed using the `-n` or `+n` switches! +## With line numbers **not** starting from 1 {#with-line-numbers-not-starting-from-1} #### Org source {#org-source} @@ -105,7 +91,7 @@ Note 2 {{< /highlight >}} -## With line numbers {#source-blocks-with-highlighting-with-linenums} +## With line numbers {#with-line-numbers} #### Org source {#org-source} diff --git a/test/site/content/posts/source-block-with-highlighting.md b/test/site/content/posts/source-block-with-highlighting.md index e729e74c..93b114a1 100644 --- a/test/site/content/posts/source-block-with-highlighting.md +++ b/test/site/content/posts/source-block-with-highlighting.md @@ -1,7 +1,7 @@ +++ title = "Source blocks with highlighting (Goldmark)" aliases = ["/posts/source-block-with-highlighting-goldmark"] -tags = ["src-block", "annotations", "goldmark", "syntax-highlighting"] +tags = ["src-block", "annotations", "goldmark", "highlight"] draft = false +++ diff --git a/test/site/content/posts/source-block-with-line-numbers-blackfriday.md b/test/site/content/posts/source-block-with-line-numbers-blackfriday.md index 77b3860e..e15139cd 100644 --- a/test/site/content/posts/source-block-with-line-numbers-blackfriday.md +++ b/test/site/content/posts/source-block-with-line-numbers-blackfriday.md @@ -8,7 +8,7 @@ draft = false - [Hugo `highlight` shortcode with line numbers](https://gohugo.io/content-management/syntax-highlighting/) -## Cases {#source-block-line-number-cases} +## Cases {#cases} ### Default new line number start {#default-new-line-number-start}