How to use org mode in Hugo

Did you know that Hugo supports formats other than markdown for content? If you are already using org mode, than you can continue to use it for writing in Hugo as well.

Recap of Org Mode:

Org Mode is a powerful and versatile document editing mode in Emacs that combines outlining, task management, and markup features. Originally designed for note-taking and project organization, Org Mode has evolved into a comprehensive tool for writing and structuring documents efficiently.

Org Mode vs. Markdown:

While both Org Mode and Markdown are markup languages, Org Mode offers a more feature-rich and extensible environment. Markdown is widely used for its simplicity, especially in web development, while Org Mode, being Emacs-centric, provides a broader range of functionalities beyond simple markup.

Formatting in Org for Hugo

Let's see how some common formatting tasks can be accomplished in Hugo using the org format

Common text formatting

Sno	Markdown	Org Mode	Comments
1	`# Heading 1`	`* Heading 1`	Heading
2	`## Heading 2`	`** Heading 2`	Sub-heading
3	`Bold Text`	`Bold Text`	Bold text
4	`Italic Text`	`/Italic Text/`	Italic text
5	`<u>Underline</u>`	`_Underline_`	Underline text
6	`` `Verbatim` ``	`=Verbatim=`	Verbatim text
7	`` `code` ``	`~code~`	Inline code
8	`~~Strike-through~~`	`+Strike-through+`	Strike-through text
9	`[Link](https://example.com)`	`[[https://example.com][Link] ]`	Hyperlink

Adding images

In Org Mode, you can include an image with alt and title tags, along with custom width and height, using the following syntax:

#+ATTR_HTML: :width 100% :height 100% :class border-2 :alt Description of the image :title Image title
[[./path/to/image.jpg]]

Result

Explanation:

[[./path/to/image.jpg] ]: This is the basic syntax for adding an image in Org Mode. Replace './path/to/image.jpg' with the actual path to your image file.

#+ATTR_HTML: :width 100% :height 100% :class border-2 :alt Description of the image :title Image title

This line is used to provide additional attributes to the HTML output. Replace 'Description of the image' with your alt text, 'Image title' with your title text, and adjust the width and height values accordingly.

Adding custom HTML

To embed HTML code in Org Mode, you can use the #+HTML: keyword followed by the HTML content. Here's an example:

#+HTML: <div class="example">This is an example HTML div.</div>

In this example, a simple HTML <div> element with a class is inserted into the Org Mode document.

This pattern can be extended for more complex HTML, involving styles, scripts, and other HTML elements.

Adding code blocks

To include code blocks in Org Mode, use the following syntax:

#+begin_src language
Your code here.
#+end_src

These code blocks preserve syntax highlighting and formatting. Adjust the language and code content as necessary for your specific use case.

Adding metadata

Hugo Front Matter serves as metadata for the content, consisting of key-value pairs such as title, date, tags, etc. This metadata assists Hugo in generating the HTML for the content.

In Org Mode, metadata is supported through a collection of keywords presented in the format #+KEY: VALUE. The front matter section is delineated by lines starting with #+, and any line not beginning this way marks the end of the front matter. Values for keywords can be individual strings (e.g., #+KEY: VALUE) or a space-separated list enclosed in square brackets (e.g., #+KEY[]: VALUE_1 VALUE_2).

Here are some common variables used in front matter and example of how to use them in org mode:

Hugo Front Matter Variables:

title: The title of your content.
date: When your content was born.
tags: Keywords defining your content.
draft: Set to true if your content is still a work in progress.
author: The creator of the content.
slug: A user-defined URL-friendly version of the title.
description: A brief summary of your content.
categories: Grouping for your content.
image: The main image associated with your content.
weight: Determines the order in lists.
lastmod: The date your content was last modified.
keywords: Additional terms to enhance discoverability.
layout: The template layout for your content.
series: The series to which your content belongs.
summary: A concise overview of your content.
type: The type or format of your content.

Usage in org mode

#+TITLE: Your Amazing Blog Post
#+DATE: 2024-01-12
#+TAGS[]: Hugo Org-Mode Writing
#+DRAFT: false
#+AUTHOR: Your Name
#+SLUG: amazing-blog-post
#+DESCRIPTION: A captivating journey into the world of Hugo and Org Mode.
#+CATEGORIES: Tech
#+IMAGES[]: /images/amazing-blog-post.jpg
#+WEIGHT: 10
#+LASTMOD: 2024-01-13
#+KEYWORDS[]: Hugo Org-Mode Tutorial
#+LAYOUT: post
#+SERIES: TechExploration
#+SUMMARY: Uncover the magic of using Hugo and Org Mode for seamless content creation.
#+TYPE: Tutorial

*Your Main Content
This is where the magic happens. Write your awesome content here!

Limitations

Due to the space-separated format, a constraint arises when dealing with multi-word values. In cases like tags or keywords, where typically spaces are natural separators, Org Mode necessitates the use of hyphens or underscores to represent multiple words. This limitation restricts the straightforward use of spaces within individual values for these metadata keys.

Example of Limitation and Resolution in Tags:

Consider the following attempt to use multi-word tags:

#+TAGS[]: Multi Word Tag

This will not work seamlessly due to the space limitation in Org Mode. To overcome this, use hyphens or underscores:

#+TAGS[]: Multi-Word-Tag

#+TAGS[]: Multi_Word_Tag

This ensures proper interpretation of multi-word tags in Org Mode metadata.

Exploring further

How org mode works in Hugo: Hugo interprets Org Mode files using the parser from the go-org repository, which is developed by Niklas Fasching. This parser is specifically designed to handle Org Mode syntax and is utilized by Hugo for rendering Org Mode content.

The go-org repository contains the Org Mode parser library that Hugo utilizes. Refer to the repository for details on the parser's capabilities and implementation.

Example Org Mode Content: To understand how to structure Org Mode content for Hugo, explore the examples provided in the go-org repository. The repository includes sample Org Mode files that demonstrate how Hugo interprets and renders Org Mode content.