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
keyword1. - 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 orC-h i g (org) Tag inheritance
- About
#+tags
– Setting Tags orC-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
.
#+filetags
will have no effect in file-based export flow.
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
- For only subtree-based exports, you can set that special tag as Org style tags too. Example:
* I don't want to export this post :no_no_dont_export:
.. and don’t forget to add that tag toorg-export-exclude-tags
too! [return]