Skip to main content

How to use org mode in Hugo

·967 words·5 mins
Hugo
pdyc
Author
pdyc
Table of Contents

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

Description of the image

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

or

#+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.

Related

How to add search to a website using flexsearch
·2373 words·12 mins
Hugo
TLDR; Describes how to implement local search using flexsearch js library to website
Migrating existing page to hugo static site generator
·1227 words·6 mins
Hugo
TLDR: How to migrate existing site to Hugo
Using shadcn ui with adobe's react aria
··747 words·4 mins
Shadcn React-Aria Radix-Ui
TLDR; use jolly-ui with shadcn to get shadcn styles with react aria components
Introduction to Tanstack Query and organizing code with queryOptions for maintainability
··4312 words·21 mins
Tanstack-Query
TLDR; Introduction to tanstack query and organizing apis with queryoptions for better maintainibility
Grouping, filtering and aggregation in Tanstack table
·1942 words·10 mins
Tanstack-Table React
TLDR; Grouping, aggregation, filtering, pagination of data in tanstack table without user input
How to add custom styling in tanstack react table
··1983 words·10 mins
Tanstack-Table React
TLDR; How to use tanstack table in react and add custom styling with meta column definitions