I have two large publishing needs: (1) creating pdfs by LaTeX and (2) writing stuffs on this Hugo-powered website i.e. to write Blackfriday-compatible Markdown files.
Nowadays, I neither write LaTeX or Markdown documents directly, but instead write in Emacs Org-mode and convert the document to my desired format. I mentioned my Org-mode setups for pdfs on this website 5 years ago and my configurations have slowly evolves since then. On the website publishing side, the excellent package ox-hugo works nicely.
For the last year, from when I started grad school, I have been writing within Org-mode extensively and it has been a pleasant experience so far. The recent versions of Org-mode support key features for academic writings like citations, and the developing version of Org-mode features a LaTeX math previewing system that will soon be the best thing we have on the market (just you wait!).
Sooner or later, when you use the same tool for two making two different types of documents, you start to wonder how far you can push it. Both LaTeX and this Hugo-based website have their own intricacies, which might make it difficult to use the same Org-mode source to publish to both pdfs and Hugo at the same time, so I didn’t consider the possibility very throughoutly.
My opinion changed when I write a pdf to share some of my experiments to my friends. “What would happen if I convert this Org-mode file to a blog post on my website, without modifying it too much?” – I thought to myself, and so I did. To my surprise, the exportation process works out of the box!.
Fast forward a few months later. The semester is now ended and I have more time to play around with this idea.
Let’s first list the things that already works across platforms:
- Citations and bibliography
- Rendering math equations
- Footnotes as sidenotes
- Notices/boxes
- Tikz equations
This post describe my attempts to reach feature-parity between my pdf documents and this Hugo website .
1 Footnotes and Sidenotes
My website features sidenotes
For example, this is a sidenote.
.
Sidenotes collapse into an expand-on-click button in smaller screen.
In my website, sidenote is implemented by wrapping some texts by a sidenote shortcode.
(defun hp/org-hugo-export-footnote-as-sidenote (footnote-reference _contents info)
"Transcode a FOOTNOTE-REFERENCE element from Org to Markdown.
CONTENTS is nil. INFO is a plist used as a communication
channel."
(let* ((n (org-export-get-footnote-number footnote-reference info))
(def (org-export-get-footnote-definition footnote-reference info))
(def-exported (when def (org-export-data def info))))
(format "{{< sidenote >}}%s{{< /sidenote >}}" def-exported)))
;; Over-write the custom blackfriday export for footnote links.
(advice-add #'org-blackfriday-footnote-reference
:override #'hp/org-hugo-export-footnote-as-sidenote
'((name . "wrapper")))
;; Don't render the section for export
(advice-add #'org-blackfriday-footnote-section
:override (lambda (&rest rest) ())
'((name . "wrapper")))
2 Boxes!
(use-package org-special-block-extras
:after org
:hook (org-mode . org-special-block-extras-mode)
:config
(org-defblock warning (frame-title "Warning") (contents "")
(format
(pcase backend
(`latex "\\begin{mdframed}[
frametitlebackgroundcolor=DarkRed!15, backgroundcolor=DarkRed!5,
hidealllines=true, innertopmargin=\\topskip, roundcorner=5pt,
frametitlefont=\\sffamily\\color{DarkRed!60!black}, frametitle=%s]
%s
\\end{mdframed}")
(_ "{{< notice warning \"%s\" >}}\n%s\n{{< /notice >}}"))
frame-title contents))
(org-defblock info (frame-title "Info") (contents "")
(format
(pcase backend
(`latex "\\begin{mdframed}[
frametitlebackgroundcolor=Teal!15, backgroundcolor=Teal!5,
hidealllines=true, innertopmargin=\\topskip, roundcorner=5pt,
frametitlefont=\\sffamily\\color{Teal!60!black}, frametitle=%s]
%s
\\end{mdframed}")
(_ "{{< notice info \"%s\" >}}\n%s\n{{< /notice >}}"))
frame-title contents))
(org-defblock tips (frame-title "Tips") (contents "")
(format
(pcase backend
(`latex "\\begin{mdframed}[
frametitlebackgroundcolor=ForestGreen!15, backgroundcolor=ForestGreen!5,
hidealllines=true, innertopmargin=\\topskip, roundcorner=5pt,
frametitlefont=\\sffamily\\color{ForestGreen!60!black}, frametitle=%s]
%s
\\end{mdframed}")
(_ "{{< notice tip \"%s\" >}}\n%s\n{{< /notice >}}"))
frame-title contents))
)