Support ox-hugo export backend

[authsec]

I try to use ox-hugo as an export backend the exporter however does not recognize the parameter values of the special blocks. After a discussion on reddit the ox-hugo creator/maintainer mentioned to raise an issue here, as this seems to be something that he cannot fix on his end.

Problem

When doing a LaTeX export, the stutter example works and repeats 5 times, however on ox-hugo export the repeat only happens 2 times, as seems to be the function default. The presumption is that the parameters of the #begin_noteblock block are ignored by org-special-block-extras when exporting using ox-hugo.

Configuration

The package configuration looks like:

 (use-package org-special-block-extras
       :ensure t
       :after org
       :hook (org-mode . org-special-block-extras-mode)
       ;; All relevant Lisp functions are prefixed ‘o-’; e.g., `o-docs-insert'.

       :config
       (o-defblock noteblock (title "Note") (title-color "primary")
		   "Define noteblock export for docsy ox hugo"
		   (apply #'concat
			  (pcase backend
			    (`latex `("\\begin{noteblock}", contents, "\\end{noteblock}"))
			    (`hugo `("{{% alert title=\"", title, "\" color=\"", title-color, "\" %}}\n", contents, "\n{{% /alert %}}"))
			    )
			  )
		   )
       (o-defblock cautionblock (title "Caution") (title-color "warning")
		   "Awesomebox caution"
		   (apply #'concat
			  (pcase backend
			    (`latex `("\\begin{cautionblock}", contents, "\\end{cautionblock}"))
			    (`hugo `("{{% alert title=\"", title, "\" color=\"", title-color, "\" %}}\n", contents, "\n{{% /alert %}}"))
			    )
			  )
		   )
       )

The org parts in using them look like:

  #+begin_noteblock
  This is a noteblock info environment from the awesomebox LaTeX package.
  #+end_noteblock

  #+begin_stutter 5
  gaga
  #+end_stutter
 
  Some blabla blabli and a little bit of a plantuml file, make sure to put the code to render the image and also add some attributes on top of the =#RESULTS:= line under which the generated image is displayed. You can control the image layout with these attributes when rendered to LaTeX.

  #+begin_cautionblock 
  Danger, Will Robinson!

  It is possible to use the blocks
  #+end_cautionblock

A screenshot of how this currently renders:

From left to right (org source, ox-hugo output using the docsy theme, LaTeX output)

[alhassy]

Hey @authsec, nice screenshots!

Unfortunately, I'm not very familiar with ox-hugo, but from a cursoury glance it seems that ox-hugo has it's own support for special blocks: It looks like that there are CSS style definitions for the resulting HTML tags.

It may be best to ask @kaushalmodi of ox-hugo to take a look. In particular, to whether ox-hugo performs any translation phase wrt special blocks; e.g., whether org-export-before-processing-hook is used? [This hook is the main way my package can do its thing.]

• It seems @kaushalmodi has an idea of why the stutter blocks won't work; perhaps he can elaborate on that futher. (Unless he's talking about CSS support; not sure.)
• These Hugo shortcods, whatever they are, seem very interesting and in the spirit of this package. I'd love to hear more about them!
• In particular, @authsec do these Hugo shortcodes give a nice interface-equivalent for block arguments? Apparently the answer is yes?

For now, @authsec, an alternative to shortcodes, one thing to try is to mimic ox-hugo's nesting for block arguments via nested blocks; but this is far from ideal.

• Incidentally, this issue may be related to defblock fails to export output when using latex derived backend  #12; which apparently has a workaround ---which I have not yet inspected.

[alhassy]

Hey @authsec, and @kaushalmodi, there is now a solution to this issue over at #12 (comment). Let me know if that works for your needs 😁

[kaushalmodi]

@alhassy Apologies for not replying sooner. I don't have much to comment because I am not using this package.

I hope that the original poster @authsec can provide some feedback to your reply.

I understand how disheartening it can be when you spend time and effort to reply to an issue and then you hear nothing from the original poster.

[authsec]

Hi @alhassy/@kaushalmodi,

I managed to make it work again with the following (doom) config snippet:

(use-package! org-special-block-extras
  :ensure t
  :after org
  :hook (org-mode . org-special-block-extras-mode)
  :config
  (defun ospe-add-support-for-derived-backend (new-backend parent-backend)
    "See subsequent snippet for a working example use."
    (add-to-list 'org-export-filter-parse-tree-functions
                 `(lambda (tree backend info)
                    (when (eq backend (quote ,new-backend))
                      (org-element-map tree 'export-block
                        (lambda (el)
                          (when (string= (org-element-property :type el) (s-upcase (symbol-name (quote ,new-backend))))
                            (org-element-put-property el :type (s-upcase (symbol-name (quote ,parent-backend))))))))
                    tree)))
(progn
;; Register new backend
(ospe-add-support-for-derived-backend 'hugo 'html)
;; Register new special block
(org-defblock noteblock (title "Note") (titleColor "primary")
            "Define noteblock export for docsy ox hugo"
            (if ;; ≈ (or (equal backend 'latex) (equal backend new-backend) ⋯)
                (org-export-derived-backend-p backend 'hugo)
                (format "{{%% alert title=\"%s\" color=\"%s\"%%}}\n%s{{%% /alert %%}}" title titleColor raw-contents) title titleColor
                raw-contents))
)
)

The interesting thing to me is, that it seems to export to latex as intended. The built-in stutter command e.g. takes the arguments just fine and repeats the words to stutter, for 5 times (in my example). The export to Hugo however does not do that. If I look at the generated markdown file, the words to stutter are repeated for 2 times only, which is the built-in default.

@kaushalmodi Is it possible, that the Hugo exporter "eats" the arguments and doesn't pass them on to the derived? markdown exporter backend? If I do use the markdown exporter directly, the words are repeated 5 times, as expected.

[kaushalmodi]

Is it possible, that the Hugo exporter "eats" the arguments and doesn't pass them on to the derived? markdown exporter backend?

ox-hugo defines org-hugo-special-block and handles some special blocks there, and then delegates the parsing of other special blocks to org-blackfriday-special-block. Nothing ever gets passed on to org-md-special-block.

As I haven't looked into the internals of this package, I don't know how you are getting the "stutter" special block to work even with its default repeat count of 2.

[authsec]

Thanks for the explanation, I was just wild guessing, as I found it was strange that the other exporters seem to do it. My elisp Kung-Fu is quite bad.

You can get the stutter block to work, if you load OSBE and then put this in a org file and export the org file:

#+begin_stutter 5
gaga
#+end_stutter

The example would simply repeat the word gaga 5 times if it works correctly and only 2 times if it's using the defaults.

[authsec]

@kaushalmodi I just found out that if I'm exporting using [h] File to Md file, the stutter block and therefore the repetitions work, whereas if I'm using [A] All subtrees (or File) to Md file(s) it doesn't.

Does that help you in anyway?