2024-03-29
Disclaimer: Emacs is necessary for being able to do the things shown below.
Excluding chats, %99 of what I write is written in org mode. I love org mode that much, but of course there are downsides. For example, while they are easy to access on my mac, if I want to view them on my iPhone, I have to jump through a bunch of hoops. And this is not the only obstacle I have to overcome. If I want to share my notes with my friends, good luck to me.
This would be my life if they weren't a handy program called pandoc. With pandoc, I can convert my documents into great-looking, properly edited word and html documents. For example, the blog post you are reading right now is completely written in org mode and converted with pandoc. Let's see how I achieve this workflow.
While it isn't always necessary, setting metadata is important for bunch of reasons like searchability and giving the general idea about the document. For example, here is the basic metadata for this document.
#+TITLE: My Org+Pandoc Workflow
#+AUTHOR: İsmail Efe Top
#+DATE: 2024-03-29
#+LANGUAGE: en
#+DESCRIPTION: How I use pandoc to transform my org documents to beautiful looking word documents and websites!Normally, turning a org document into a word document is easy if you have the pandoc package. But I use a thing called reference template. In this use-case, I have a document called custom-reference.docx. This documents has all the changes I made to the default font-size, heading fonts, colors etc. When I tell pandoc to use that document as a reference. It turns my org documents into the perfect docx file. Figuring out how to use and automate this took a really long time but I am really glad I done the necessary work.
I use this automation everyday to turn my notes into a docx file and then a pdf. It is really useful when I want to summit a homework or share my class notes with a friend.
I use a function to achieve this, here is what you have to do to use my function.
You can download mine and change it however you like. Put it in somewhere safe and note the file-path.
For pandoc, you can use homebrew or any other package manager.
For pandoc-mode, you can install the package with melpa and read more here.
For ox-pandoc, you can install the package with melpa and read more here.
;; put this on your init.el or config.el
(setq pandoc-binary "/opt/homebrew/bin/pandoc")I installed pandoc with homebrew, if you don't know where your pandoc binary is located you can run 'whereis pandoc' in your terminal.
;; put this on your init.el or config.el
(setq pandoc-data-dir "/Users/example_user/.config/doom/etc/pandoc/")You can set this directory to wherever you like.
This file goes into your pandoc data directory.
It is really important to use a proper configuration file, this file is what makes pandoc recognize the reference docx document.
As an example or a starting point, you can download my docx.pandoc file here. Don't forget to change the path of the reference docx file (reference-doc) to the one you noted at the beginning.
;; put this on your init.el or config.el
(defun efe/export-to-docx ()
"Output to docx using pandoc-mode"
(interactive)
(pandoc-mode)
(execute-kbd-macro (kbd "C-c / O W d b b r"))
(setq pandoc-mode nil)
)When you run this function, it creates a docx file with the same name as your original file.
Here is how I turn my org documents into blog posts. Firstly, before exporting my org documents I run a function that adds the necessary html heads and bottom headers.
;; put this on your init.el or config.el
(defun insert-html-blog-template ()
"Inserts HTML_HEAD lines at the first empty line and html code at the end of the buffer."
(interactive)
(save-excursion
(goto-char (point-min))
(let ((empty-line (progn (re-search-forward "^$" nil t) (point))))
(goto-char empty-line)
(insert "\n#+HTML_HEAD: <link rel=\"webmention\" href=\"https://webmention.io/ismailefe.org/webmention\" />\n")
(insert "#+HTML_HEAD: <link rel=\"stylesheet\" type=\"text/css\" href=\"/templates/style.css\" />\n")
(insert "#+HTML_HEAD: <link rel=\"apple-touch-icon\" sizes=\"180x180\" href=\"/favicon/apple-touch-icon.png\">\n")
(insert "#+HTML_HEAD: <link rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/favicon/favicon-32x32.png\">\n")
(insert "#+HTML_HEAD: <link rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/favicon/favicon-16x16.png\">\n")
(insert "#+HTML_HEAD: <link rel=\"manifest\" href=\"/favicon/site.webmanifest\">\n")))
(goto-char (point-max))
(insert "\n\n")
(insert "#+BEGIN_EXPORT html\n")
(insert "<div class=\"bottom-header\">\n")
(insert " <a class=\"bottom-header-link\" href=\"/\">Home</a>\n")
(insert " <a href=\"mailto:ismailefetop@gmail.com\" class=\"bottom-header-link\">Mail Me</a>\n")
(insert " <a class=\"bottom-header-link\" href=\"/feed.xml\" target=\"_blank\">RSS</a>\n")
(insert " <a class=\"bottom-header-link\" href=\"https://github.com/Ektaynot/ismailefe_org\" target=\"_blank\">Source</a>\n")
(insert "</div>\n")
(insert "<div class=\"firechickenwebring\">\n")
(insert " <a href=\"https://firechicken.club/efe/prev\">←</a>\n")
(insert " <a href=\"https://firechicken.club\">🔥🐓</a>\n")
(insert " <a href=\"https://firechicken.club/efe/next\">→</a>\n")
(insert "</div>\n")
(insert "#+END_EXPORT\n"))This function adds this on the top of the document (you can find my stylesheet here)
#+HTML_HEAD: <link rel="webmention" href="https://webmention.io/ismailefe.org/webmention" />
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="/templates/style.css" />
#+HTML_HEAD: <link rel="apple-touch-icon" sizes="180x180" href="/favicon/apple-touch-icon.png">
#+HTML_HEAD: <link rel="icon" type="image/png" sizes="32x32" href="/favicon/favicon-32x32.png">
#+HTML_HEAD: <link rel="icon" type="image/png" sizes="16x16" href="/favicon/favicon-16x16.png">
#+HTML_HEAD: <link rel="manifest" href="/favicon/site.webmanifest">And adds this on the end of the document
<div class="bottom-header">
<a class="bottom-header-link" href="/">Home</a>
<a href="mailto:ismailefetop@gmail.com" class="bottom-header-link">Mail Me</a>
<a class="bottom-header-link" href="/feed.xml" target="_blank">RSS</a>
<a class="bottom-header-link" href="https://github.com/Ektaynot/ismailefe_org" target="_blank">Source</a>
</div>
<div class="firechickenwebring">
<a href="https://firechicken.club/efe/prev">←</a>
<a href="https://firechicken.club">🔥🐓</a>
<a href="https://firechicken.club/efe/next">→</a>
</div>With these snippets added, all I have to do is run the 'org-pandoc-export-to-html5' function in Emacs (this function comes with ox-pandoc). This creates a html file with the same name as the original file.
As you see, pandoc is a must for me when using org mode. While I invested a great time to learn these tools, they more than paid for themselves. I recommend everyone to follow a similiar path.
If you have questions or feedback, feel free to email me!