Tags and Categories

Subtree-based Export #

Tags #

Tags for subtree-based exports can be set using the EXPORT_HUGO_TAGS property or the usual Org tags in the post subtree heading.

By default, Org tags from parent headings, and the tags set in the #+filetags keyword get inherited (as the default value of org-use-tag-inheritance is t).

Example #

* My post                                                         :tag1:tag2:

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.

Categories #

Categories for subtree-based exports can be set using the EXPORT_HUGO_CATEGORIES property or the usual Org tags in the post subtree heading (but tags with @ prefix).

For subtree-based exports, the Hugo front-matter categories values are derived from Org tags set for the post subtree heading (if EXPORT_HUGO_CATEGORIES is not set), but only the ones prefixed with @.

As with the tags, by default, the categories (Org tags with “@” prefix) from parent headings, and the ones set in the #+filetags keyword too get inherited (as the default value of org-use-tag-inheritance is t).

Example #

* My post                                                       :@cat1:@cat2:

#+filetags: tag1 tag2 @cat1 @cat2
* My post                                                       :tag3:@cat3:

Above, the “My post” will end up have all tags (“tag1”, “tag2”, “tag3”) and all categories (“cat1”, “cat2”, “cat3”) if org-use-tag-inheritance is t.

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

#+tags keyword has some special uses in Org documents.

List of available tags for the current file

It’s used for providing a list of tags at the top of an Org file which gets added to the pool of tags for auto-completion (see Org Info: Setting Tags or C-h i g (org) Setting Tags).

Tag hierarchy definition

The #+tags keyword is also used to define Tag Hierarchies. See Org Info: Tag Hierarchy (or C-h i g (org) Tag Hierarchy).

And the Org manual already has a dedicated keyword #+filetags to provide a list of tags to apply to the current file (see Org Info: Tag Inheritance or C-h i g (org) Tag inheritance). So ox-hugo recognizes #+filetags and not #+tags to collect the tags assigned for the current post.

File-based Export #

Tags #

Tags for file-based exports can be set using the #+hugo_tags or #+filetags keyword.

Categories #

Categories for file-based exports can be set using the #+hugo_categories or #+filetags keyword.

Example #

#+filetags: tag1 tag2 @cat1 @cat2

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.

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.

Sub-heading Tags #

Sub-heading tags are exported wrapped in HTML span tags to the right of the exported heading if org-export-with-tags is non-nil (default) or if #+options: tags:t is used.

The span tags are best formatted using CSS. Here’s one example:

.tag span {
    background: lightgrey;
    font-size: small;
    padding: 0.1rem 0.2rem;
    margin: 0.2rem;
}

Search the ox-hugo test site for “subheading-tags” examples.

More Examples #

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