Tags and Categories

Subtree-based Export #

Tags #

For subtree-based exports, the Hugo front-matter tags values are derived from Org tags set for the post subtree headline.

Example:

* My post                                                         :tag1:tag2:

By default, Org tags from parent headlines, and the tags set in the #+filetags keyword get inherited (as the default value of org-use-tag-inheritance is t). If the tag inheritance doesn’t work as expected, check that the value of that variable is set as required.

If the EXPORT_HUGO_TAGS property is set for a valid Hugo post subtree, the value of that property will completely override the Org tags set even on that subtree, the inherited values of Org-style tags from parent headlines and even #+filetags.

Marking files to not be exported #

Note that if you want to prevent a file from getting exported, you can assign a special tag to the whole file (example: no_no_dont_export).

• For per-subtree flow, that don’t export tag has to be set using the #+filetags keyword¹.
• For per-file flow, that same dont’ export tag has to be set using the #+hugo_tags keyword (because #+filetags keyword does not work for per-file flow. See File-based Export).

Then in your export setup, add that special tag to the org-export-exclude-tags variable. You can grep through this repo for the special tag dont_export_during_make_test that is used to mark few Org files to not be exported when running the tests.

Why use #+filetags and not #+tags? #

• About #+filetags – Tag Inheritance or C-h i g (org) Tag inheritance
• About #+tags – Setting Tags or C-h i g (org) Setting tags

Categories #

For subtree-based exports, the Hugo front-matter categories values are derived from Org tags set for the post subtree headline, but only the ones prefixed with @.

Example:

* My post                                                       :@cat1:@cat2:

As with the tags, by default, the categories (Org tags with “@” prefix) from parent headlines, and the ones set in the #+filetags keyword too get inherited (as the default value of org-use-tag-inheritance is t). If the tag inheritance doesn’t work as expected, check that the value of that variable is set as required.

If the EXPORT_HUGO_CATEGORIES property is set for a valid Hugo post subtree, the value of that property will completely override the categories set even on that subtree, the inherited values of categories from parent headlines and even #+filetags.

File-based Export #

The tag (and category) inheritance does not apply to the file-based export flow. So #+filetags will have no effect in this flow.

• To set tags, use #+hugo_tags.
• To set categories, use #+hugo_categories.

Hyphens and Spaces in Org tags (and categories) #

Hyphens and spaces are not allowed in Org tags (* Heading :TAG:).

So ox-hugo converts:

• single underscores to hyphens if org-hugo-prefer-hyphen-in-tags is set to non-nil (default).
• double underscores to spaces if org-hugo-allow-spaces-in-tags is set to non-nil (default).

So an Org tag abc_def will be exported as tag “abc-def”, and abc__def will be exported as tag “abc def”.

The same applies to Org tags with prefix @ which will be exported as categories. So @abc_def will be exported as category “abc-def”, and @abc__def as category “abc def”.

To export a tag or category with an underscore, use 3 consecutive underscores. So an Org tag abc___def will be exported as tag “abc_def” (and the same for categories). If you rather prefer to always export single underscores as underscores, set org-hugo-prefer-hyphen-in-tags to nil.

NOTE

These two variables also affect the tags set via #+filetags keyword (which is used only in subtree-based exported Org files).

These variables do not affect the tags set via keywords #+hugo_tags, #+hugo_categories or #+keywords (or their respective subtree property forms), because Org keywords and properties allow using the hyphen and space (in “double-quoted strings”) characters. So the underscores in these keywords remain untransformed on export.

Examples #

• Org source
• Exported Markdown – inheriting-tags.md, overriding-tags.md
• Hugo-generated HTML – Inheriting tags, Overriding tags