Support ox-hugo export backend
Closed this issue · 7 comments
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)
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
stutterblocks 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 #12; which apparently has a workaround ---which I have not yet inspected.
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 😁
@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.
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.
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.
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.
@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?