#+title: Ox-Zola #+author: Giovanni Crisalfi [[https://www.gnu.org/licenses/gpl-3.0][https://img.shields.io/badge/License-GPL%20v3-blue.svg]]

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 [[https://www.getzola.org/][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.

Having a dedicated package with a different name is also helpful to let Zola users find this solution.

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 [[https://ox-hugo.scripter.co/][ox-hugo documentation]] to have a grasp of how the entire exporter works.

#+begin_quote 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-zola= doesn't break =ox-hugo=! #+end_quote

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.

• Installation 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=:

#+begin_src emacs-lisp (straight-use-package '(ox-zola :host github :repo "gicrisf/ox-zola" :files (:defaults "*.el" "backend" "stylesheets") :includes ox-hugo)) #+end_src

Install with use-package:

#+begin_src emacs-lisp (use-package ox-zola :ensure t :after ox :config (require 'ox-hugo)) #+end_src

If you're on Doom Emacs like me, you can install with the =package!= macro:

#+begin_src emacs-lisp ;; Remember, org-hugo is required (package! ox-hugo) (package! ox-zola :recipe (:host github :repo "gicrisf/ox-zola")) #+end_src

• Quick start You have two options for getting started:

1. Configure your metadata inside the Org file.
2. 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:

#+begin_src org #+zola_base_dir: /path/to/your/zola/project #+zola_section: posts #+end_src

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:

#+begin_src org ,* My First Post :PROPERTIES: :EXPORT_FILE_NAME: my-first-post :END: This is my first post written in Org-mode! #+end_src

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:

#+begin_src org ,* My First Post :@blogging:emacs: #+end_src

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:

#+begin_src org ,* My First Post :@blogging:emacs: :PROPERTIES: :EXPORT_HUGO_SECTION: posts/emacs-my-first-post :EXPORT_FILE_NAME: index :END: #+end_src

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.

• Zola taxonomies You can also set taxonomies at the top of the file like this:

#+begin_src org #+zola_categories: blogging #+zola_tags: whatever you want #+end_src

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:

#+begin_src toml title = "Title" author = ["You"] categories = ["blogging"] tags = ["whatever", "you", "want"] #+end_src

it will reproduce the Zola hierarchy:

#+begin_src toml title = "Title" author = ["You"]

[taxonomies] categories = ["blogging"] tags = ["whatever", "you", "want"] #+end_src

• Features

• [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

• Donate Did you find this package useful? Why don't you help me keep awake by buying me a coffee?

[[https://ko-fi.com/V7V425BFU][https://ko-fi.com/img/githubbutton_sm.svg]]

• License Open sourced under the [[./LICENSE][GPL-3.0 license]].