Ox-zola is an Org exporter backend that streamlines Emacs users’ conversion from Org mode to Markdown, caring for both the body and the TOML frontmatter in a way that’s compatible with the static site generator Zola.
It started as a fork of the famous ox-hugo exporter, but it now is a different package that runs on top of ox-hugo itself.
This way, you can receive ox-hugo updates without being restrained by the progress of this package.
Even so, I suggest pinning ox-hugo to the most recent working version to avoid breaking changes after updates.
Being this package built like a layer on top of ox-hugo, most of the stuff you can do with ox-hugo is possible with ox-zola too; so, I suggest reading the ox-hugo documentation to have a grasp of how the entire exporter works.
Usually, people use a single static site generator, but if you have different websites that happen to be generated with Zola and Hugo, you’re covered.
ox-zoladoesn’t breakox-hugo!
If something doesn’t go the right way, remember that you can open an issue and we can work together for solving the problem. Enhancement requests are appreciated too.
Since this package was born for my personal use and it’s not perfect yet, I didn’t make it available on Melpa. However, you can install it directly from this repository.
Install with straight:
(straight-use-package
'(ox-zola :host github :repo "gicrisf/ox-zola"
:files (:defaults "*.el" "backend" "stylesheets")
:includes ox-hugo))Install with use-package:
(use-package ox-zola
:ensure t
:after ox
:config
(require 'ox-hugo))If you’re on Doom Emacs like me, you can install with the package! macro:
;; Remember, org-hugo is required
(package! ox-hugo)
(package! ox-zola :recipe (:host github :repo "gicrisf/ox-zola"))You have two options for getting started:
- Configure your metadata inside the Org file.
- Configure your defaults in your Emacs configuration.
I usually prefer the second approach, but the first one is simpler, so we’ll start with that.
When you create a new Org file and want to export its content using ox-zola, add the following metadata at the top:
#+zola_base_dir: /path/to/your/zola/project
#+zola_section: posts
This allows you to target multiple blogs from different Org files. Now, let’s focus on the most important part: writing the content.
Use Org-mode headings to structure your posts. For example:
* My First Post
:PROPERTIES:
:EXPORT_FILE_NAME: my-first-post
:END:
This is my first post written in Org-mode!
Place your cursor on the heading and run M-x org-hugo-export-to-md. This will generate a Markdown file in your Zola content/posts/ directory.
To build and serve your Zola site, navigate to your site’s root directory and run the command zola serve.
If you want to add taxonomies, use Org-mode’s standard system:
* My First Post :@blogging:emacs:
This creates a category called blogging and a tag emacs. You can also override the target section and file name for a specific heading like this:
* My First Post :@blogging:emacs:
:PROPERTIES:
:EXPORT_HUGO_SECTION: posts/emacs-my-first-post
:EXPORT_FILE_NAME: index
:END:
Why would you want to do that? I use this approach to create a subdirectory containing my `index.md` file, allowing me to store related assets, such as images, in the same directory.
You can also set taxonomies at the top of the file like this:
#+zola_categories: blogging
#+zola_tags: whatever you want
When you use zola_categories and zola_tags, running
ox-zola-export-to-md or ox-zola-export-wim-to-md, the command will trigger dedicated taxonomy management. Instead of exporting the taxonomies at the root of the TOML:
title = "Title"
author = ["You"]
categories = ["blogging"]
tags = ["whatever", "you", "want"]it will reproduce the Zola hierarchy:
title = "Title"
author = ["You"]
[taxonomies]
categories = ["blogging"]
tags = ["whatever", "you", "want"]- [X] Custom frontmatters parameters for Zola
- [X] Lastmod/updated tags for Zola
- [X] Taxonomies for Zola
- [X] Zola shortcodes
- [X] Exports with images
- [X] Avoid breaking ox-hugo functions while ox-zola is installed.
- [X] Differentiate front-matter items for Zola and Hugo in the same org drawer
Did you find this package useful? Why don’t you help me keep awake by buying me a coffee?
Open sourced under the GPL-3.0 license.