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/ox-blackfriday.el b/ox-blackfriday.el index d5646775..b5b327f2 100644 --- a/ox-blackfriday.el +++ b/ox-blackfriday.el @@ -641,12 +641,15 @@ 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 +658,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 @@ -1054,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) @@ -1074,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 d1f9f117..6703af60 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,24 +1738,37 @@ 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 + (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 linenos-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)))) - - ;; 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)) - (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)))) + + (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)) + + (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)) @@ -2680,61 +2693,88 @@ 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). + +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. -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. +CONTENTS is nil. INFO is a plist used as a communication +channel. -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 +--- 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 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 (cond - ((stringp hl-lines) - (replace-regexp-in-string "," " " hl-lines)) ;"1,3-4" -> "1 3-4" - ((numberp hl-lines) - (number-to-string hl-lines)))) + ;; 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) @@ -2759,58 +2799,56 @@ 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)))) + + ;; (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)) + (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) diff --git a/test/site/content-org/all-posts.org b/test/site/content-org/all-posts.org index b65e09b5..bd1f3a82 100644 --- a/test/site/content-org/all-posts.org +++ b/test/site/content-org/all-posts.org @@ -1314,68 +1314,55 @@ This code block once again contains no backticks: #+begin_src emacs-lisp (message "Hello again x6") #+end_src -** Highlight Shortcode :highlight:shortcode: -*** Source blocks with =highlight= shortcode -:PROPERTIES: -:EXPORT_HUGO_CODE_FENCE: -:EXPORT_FILE_NAME: highlight-shortcode-src-blocks -:EXPORT_DATE: 2017-07-31 -:END: -Note that to disable the code fence option, the value portion of the -property needs to be left *empty* instead of setting to =nil=! -#+begin_example -:PROPERTIES: -:EXPORT_HUGO_CODE_FENCE: -:END: -#+end_example -#+include: "./all-posts.org::#example-text-with-code-blocks" :only-contents t -*** Source blocks with line number annotation +** Source block annotations :src_block:annotations: +*** 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]] -- [[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") @@ -1387,20 +1374,22 @@ 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 (Goldmark) :highlight: :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 +***** 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 @@ -1409,22 +1398,22 @@ 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: 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 (like =:hl_lines=), the _switches have to come first_. @@ -1432,23 +1421,142 @@ 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 +#+begin_src org :noweb yes :exports results :results output replace :eval yes +<> +#+end_src +** Highlight Shortcode :highlight:shortcode: +*** Source blocks with =highlight= shortcode +:PROPERTIES: +:EXPORT_HUGO_CODE_FENCE: +:EXPORT_FILE_NAME: highlight-shortcode-src-blocks +:EXPORT_DATE: 2017-07-31 +:END: +Note that to disable the code fence option, the value portion of the +property needs to be left *empty* instead of setting to =nil=! +#+begin_example +:PROPERTIES: +:EXPORT_HUGO_CODE_FENCE: +:END: +#+end_example +#+include: "./all-posts.org::#example-text-with-code-blocks" :only-contents t +*** Annotate code blocks need =highlight= shortcode in Blackfriday :blackfriday: +:PROPERTIES: +: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 +****** 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 +**** Source blocks with highlighting (Blackfriday) :highlight: +:PROPERTIES: +:EXPORT_FILE_NAME: source-block-with-highlighting-blackfriday +:END: +***** Without 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 +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 +******* 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 +******* 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 @@ -1640,9 +1748,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 @@ -1689,7 +1798,19 @@ 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. + +*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 *in* the list at *that* indentation level, those indentations are not @@ -1702,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 @@ -1743,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" %}} @@ -1910,12 +2032,18 @@ 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 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 @@ -1932,12 +2060,15 @@ 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 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: @@ -1952,6 +2083,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: @@ -8023,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 cb39c532..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,45 +5,54 @@ 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} -{{< 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" >}} +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 This is line 3 -{{< /highlight >}} +``` 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 +``` +
diff --git a/test/site/content/posts/source-block-indented.md b/test/site/content/posts/source-block-indented.md index 339f73bb..b0463999 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,23 @@ 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. + +**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 **in** the list at **that** indentation level, those indentations are not @@ -78,36 +93,38 @@ 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 - {{< 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..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,15 +21,15 @@ 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. -{{< 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} @@ -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 new file mode 100644 index 00000000..d6da6841 --- /dev/null +++ b/test/site/content/posts/source-block-with-highlighting-blackfriday.md @@ -0,0 +1,120 @@ ++++ +title = "Source blocks with highlighting (Blackfriday)" +tags = ["src-block", "shortcode", "blackfriday", "highlight"] +draft = false ++++ + +## Without line numbers {#without-line-numbers} + + +#### 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 {#with-line-numbers-not-starting-from-1} + + +#### 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 {#with-line-numbers} + + +#### 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..93b114a1 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", "highlight"] 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-blackfriday.md b/test/site/content/posts/source-block-with-line-numbers-blackfriday.md new file mode 100644 index 00000000..e15139cd --- /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 {#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..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,11 +1,11 @@ +++ -title = "Source blocks with line number annotation" -tags = ["src-block", "highlight", "shortcode"] +title = "Source blocks with line number annotation (Goldmark)" +aliases = ["/posts/source-block-with-line-numbers-goldmark"] +tags = ["src-block", "annotations", "goldmark", "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} @@ -26,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} @@ -47,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} @@ -68,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} @@ -89,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 >}} +```