Fix: Don't change default interpretation of #+TAGS #breaking

Fixes #89

-   Restore the default Org behavior of `#+TAGS`. Now that keyword (and
    the `EXPORT_TAGS` property) is **not** used by `ox-hugo`.

-   File-based exports must now use `#+HUGO_TAGS` to set the post tags.
-   Subtree-based exports can use the `EXPORT_HUGO_TAGS` property to
    override Org-style tags on the same headline (and the ones inherited
    from Org-style tags from any of the parent subtrees and
    `#+FILETAGS`).
    -   Note that for subtree-based exports, `#+FILETAGS` can be used to
        set tags globally in the file. Earlier `#+TAGS` was used for
        that purpose.
-   Subtree-based exports can use the `EXPORT_HUGO_CATEGORIES` property
    to override Org-style categories (tags with "@" prefix) on the same
    headline (and the ones inherited from Org-style categories from any
    of the parent subtrees and `#+FILETAGS`).
    -   Note that for subtree-based exports, `#+FILETAGS` can be used to
        set categories (tags with "@") globally in the file.

** Why use #+FILETAGS and not #+TAGS??

- About `#+FILETAGS` -- [Tag Inheritance](http://orgmode.org/manual/Tag-inheritance.html)
- About `#+TAGS` -- [Setting Tags](http://orgmode.org/manual/Setting-tags.html)

=====
See https://ox-hugo.scripter.co/doc/tags-and-categories/
=====

README.org

@@ -155,6 +155,28 @@ The common =ox-hugo= export bindings are:
 Do =M-x customize-group=, and select =org-export-hugo= to see the
 available customization options for this package.
 * Changelog
+** v0.4 <2017-10-28 Sat>
+*** Backward-incompatible changes
+- Restore the default Org behavior of =#+TAGS=. Now that keyword (and
+  the =EXPORT_TAGS= property) is *not* used by =ox-hugo=. Fixes
+  [[[https://github.com/kaushalmodi/ox-hugo/issues/89][89]]].
+- File-based exports must now use =#+HUGO_TAGS= to set the post tags.
+- Subtree-based exports can use the =EXPORT_HUGO_TAGS= property to
+  override Org-style tags on the same headline (and the ones inherited
+  from Org-style tags from any of the parent subtrees and
+ =#+FILETAGS=).
+  - Note that for subtree-based exports, =#+FILETAGS= can be used to
+    set tags globally in the file. Earlier =#+TAGS= was used for that
+    purpose.
+- Subtree-based exports can use the =EXPORT_HUGO_CATEGORIES= property
+  to override Org-style categories (tags with "@" prefix) on the same
+  headline (and the ones inherited from Org-style categories from any
+  of the parent subtrees and =#+FILETAGS=).
+  - Note that for subtree-based exports, =#+FILETAGS= can be used to
+    set categories (tags with "@") globally in the file.
+
+See the new section added to documentation:
+[[https://ox-hugo.scripter.co/doc/tags-and-categories][*Tags and Categories*]]
 ** v0.3.2 <2017-10-24 Tue>
 *** Fixes
 - Fix issue with headline metadata parsing (ALLTAGS, CLOSED, TODO)

doc/content/doc/changelog.md

@@ -6,6 +6,33 @@ draft = false
   identifier = "changelog"
 +++
 
+## v0.4 <span class="timestamp-wrapper"><span class="timestamp">&lt;2017-10-28 Sat&gt;</span></span> {#v0-dot-4}
+
+
+### Backward-incompatible changes {#backward-incompatible-changes}
+
+-   Restore the default Org behavior of `#+TAGS`. Now that keyword (and
+    the `EXPORT_TAGS` property) is **not** used by `ox-hugo`. Fixes
+    [[89](https://github.com/kaushalmodi/ox-hugo/issues/89)].
+-   File-based exports must now use `#+HUGO_TAGS` to set the post tags.
+-   Subtree-based exports can use the `EXPORT_HUGO_TAGS` property to
+    override Org-style tags on the same headline (and the ones inherited
+    from Org-style tags from any of the parent subtrees and
+    `#+FILETAGS`).
+    -   Note that for subtree-based exports, `#+FILETAGS` can be used to
+        set tags globally in the file. Earlier `#+TAGS` was used for that
+        purpose.
+-   Subtree-based exports can use the `EXPORT_HUGO_CATEGORIES` property
+    to override Org-style categories (tags with "@" prefix) on the same
+    headline (and the ones inherited from Org-style categories from any
+    of the parent subtrees and `#+FILETAGS`).
+    -   Note that for subtree-based exports, `#+FILETAGS` can be used to
+        set categories (tags with "@") globally in the file.
+
+See the new section added to documentation:
+[**Tags and Categories**](/doc/tags-and-categories)
+
+
 ## v0.3.2 <span class="timestamp-wrapper"><span class="timestamp">&lt;2017-10-24 Tue&gt;</span></span> {#v0-dot-3-dot-2}
 
 

doc/content/doc/tags-and-categories.md

@@ -0,0 +1,113 @@
++++
+title = "Tags and Categories"
+draft = false
+[menu."org_to_hugo"]
+  weight = 3005
+  identifier = "tags-and-categories"
++++
+
+## Subtree-based Export {#subtree-based-export}
+
+
+### Tags {#tags}
+
+For subtree-based exports, the Hugo front-matter `tags` values are
+derived from Org tags set for the post subtree headline.
+
+Example:
+
+```org
+* 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`.
+
+
+#### Why use `#+FILETAGS` and not `#+TAGS`? {#why-use-filetags-and-not-tags}
+
+-   About `#+FILETAGS` -- [Tag Inheritance](http://orgmode.org/manual/Tag-inheritance.html) or `C-h i g (org) Tag
+      inheritance`
+-   About `#+TAGS` -- [Setting Tags](http://orgmode.org/manual/Setting-tags.html) or `C-h i g (org) Setting tags`
+
+
+### Categories {#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:
+
+```org
+* 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 {#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 in tags (and categories) {#hyphens-in-tags--and-categories}
+
+Hyphens are not allowed in Org tags. So `ox-hugo` converts **single
+underscores** to hyphens if `org-hugo-prefer-hyphen-in-tags` is set to
+non-nil (default). So an Org tag **abc\_def** will be exported as _tag_
+**"abc-def"**. Similarly an Org tag **@abc\_def** will be exported 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"**. If you rather prefer to always export single underscores
+as underscores, set `org-hugo-prefer-hyphen-in-tags` to nil.
+
+This variable does not affect the tags set via `#+HUGO_TAGS` keyword
+or the `EXPORT_HUGO_TAGS` property, because Org keywords and
+properties allow using the hyphen character. So underscores and
+hyphens in tags (or categories in `#+HUGO_CATEGORIES` /
+`EXPORT_HUGO_CATEGORIES`) remain untransformed on export.
+
+
+## Spaces in tags (and categories) {#spaces-in-tags--and-categories}
+
+Spaces are not allowed in Org tags. So `ox-hugo` converts **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"**. Similarly an Org tag **@abc\_\_def** will be exported as
+_category_ **"abc def"**.
+
+This variable **also affects** the tags set via `#+HUGO_TAGS` keyword or
+the `EXPORT_HUGO_TAGS` property, because it is not possible to
+distinguish in Org keywords and properties whether the space is part
+of the tag or used to separate two tags. The same applies to
+categories set via `#+HUGO_CATEGORIES` / `EXPORT_HUGO_CATEGORIES`.
+
+
+## Examples {#examples}
+
+-   [Org source](https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/tags-and-categories.org)
+-   Exported Markdown -- [`inheriting-tags.md`](https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content/posts/inheriting-tags.md), [`overriding-tags.md`](https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content/posts/overriding-tags.md)
+-   Hugo-generated HTML -- [Inheriting tags](https://ox-hugo.scripter.co/test/posts/inheriting-tags/), [Overriding tags](https://ox-hugo.scripter.co/test/posts/overriding-tags/)

doc/ox-hugo-manual.org

@@ -13,6 +13,28 @@
 :PROPERTIES:
 :CUSTOM_ID: changelog
 :END:
+** v0.4 <2017-10-28 Sat>
+*** Backward-incompatible changes
+- Restore the default Org behavior of =#+TAGS=. Now that keyword (and
+  the =EXPORT_TAGS= property) is *not* used by =ox-hugo=. Fixes
+  {{{issue(89)}}}.
+- File-based exports must now use =#+HUGO_TAGS= to set the post tags.
+- Subtree-based exports can use the =EXPORT_HUGO_TAGS= property to
+  override Org-style tags on the same headline (and the ones inherited
+  from Org-style tags from any of the parent subtrees and
+ =#+FILETAGS=).
+  - Note that for subtree-based exports, =#+FILETAGS= can be used to
+    set tags globally in the file. Earlier =#+TAGS= was used for that
+    purpose.
+- Subtree-based exports can use the =EXPORT_HUGO_CATEGORIES= property
+  to override Org-style categories (tags with "@" prefix) on the same
+  headline (and the ones inherited from Org-style categories from any
+  of the parent subtrees and =#+FILETAGS=).
+  - Note that for subtree-based exports, =#+FILETAGS= can be used to
+    set categories (tags with "@") globally in the file.
+
+See the new section added to documentation:
+{{{doc(tags-and-categories,*Tags and Categories*)}}}
 ** v0.3.2 <2017-10-24 Tue>
 *** Fixes
 - Fix issue with headline metadata parsing (ALLTAGS, CLOSED, TODO)
@@ -930,6 +952,92 @@ The Org source for the below is similar to the above, except that the
 =-n= switch is also added to enable the line numbers.
 
 #+INCLUDE: "../test/site/content-org/all-posts.org::#source-blocks-with-highlighting-with-linenums-not-starting-from-1" :only-contents t
+*** Tags and Categories
+:PROPERTIES:
+:EXPORT_FILE_NAME: tags-and-categories
+:END:
+**** 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:
+#+BEGIN_SRC org
+,* My post                                                         :tag1:tag2:
+#+END_SRC
+
+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=.
+****** Why use =#+FILETAGS= and not =#+TAGS=?
+- About =#+FILETAGS= -- [[http://orgmode.org/manual/Tag-inheritance.html][Tag Inheritance]] or =C-h i g (org) Tag
+  inheritance=
+- About =#+TAGS= -- [[http://orgmode.org/manual/Setting-tags.html][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:
+#+BEGIN_SRC org
+,* My post                                                       :@cat1:@cat2:
+#+END_SRC
+
+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 in tags (and categories)
+Hyphens are not allowed in Org tags. So =ox-hugo= converts *single
+underscores* to hyphens if =org-hugo-prefer-hyphen-in-tags= is set to
+non-nil (default). So an Org tag *abc_def* will be exported as /tag/
+*"abc-def"*. Similarly an Org tag *@abc_def* will be exported 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"*. If you rather prefer to always export single underscores
+as underscores, set =org-hugo-prefer-hyphen-in-tags= to nil.
+
+This variable does not affect the tags set via =#+HUGO_TAGS= keyword
+or the =EXPORT_HUGO_TAGS= property, because Org keywords and
+properties allow using the hyphen character. So underscores and
+hyphens in tags (or categories in =#+HUGO_CATEGORIES= /
+=EXPORT_HUGO_CATEGORIES=) remain untransformed on export.
+**** Spaces in tags (and categories)
+Spaces are not allowed in Org tags. So =ox-hugo= converts *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"*. Similarly an Org tag *@abc__def* will be exported as
+/category/ *"abc def"*.
+
+This variable *also affects* the tags set via =#+HUGO_TAGS= keyword or
+the =EXPORT_HUGO_TAGS= property, because it is not possible to
+distinguish in Org keywords and properties whether the space is part
+of the tag or used to separate two tags. The same applies to
+categories set via =#+HUGO_CATEGORIES= / =EXPORT_HUGO_CATEGORIES=.
+**** Examples
+- [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/tags-and-categories.org][Org source]]
+- Exported Markdown -- [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content/posts/inheriting-tags.md][=inheriting-tags.md=]], [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content/posts/overriding-tags.md][=overriding-tags.md=]]
+- Hugo-generated HTML -- [[https://ox-hugo.scripter.co/test/posts/inheriting-tags/][Inheriting tags]], [[https://ox-hugo.scripter.co/test/posts/overriding-tags/][Overriding tags]]
 * COMMENT Local Variables                                           :ARCHIVE:
 # Local Variables:
 # fill-column: 70

ox-hugo.el

@@ -5,7 +5,7 @@
 ;; URL: https://ox-hugo.scripter.co
 ;; Package-Requires: ((emacs "24.5") (org "9.0"))
 ;; Keywords: Org, markdown, docs
-;; Version: 0.3.2
+;; Version: 0.4
 
 ;;; Commentary:
 
@@ -578,14 +578,20 @@ The auto-copying behavior is disabled if this variable is set to nil."
                    ;; slug
                    (:hugo-slug "HUGO_SLUG" nil nil)
                    ;; taxomonomies - tags, categories
-                   ;; Org tags parsed from posts as subtrees get the
-                   ;; highest precedence as tag names.
-                   (:tags "TAGS" nil nil newline)
                    (:hugo-tags "HUGO_TAGS" nil nil newline)
-                   ;; Org tags starting with "@" parsed from posts as
-                   ;; subtrees get the highest precedence as category
-                   ;; names.
+                   ;; #+HUGO_TAGS are used to set the post tags in Org
+                   ;; files written for file-based exports.  But for
+                   ;; subtree-based exports, the EXPORT_HUGO_TAGS
+                   ;; property can be used to override inherited tags
+                   ;; and Org-style tags.
                    (:hugo-categories "HUGO_CATEGORIES" nil nil newline)
+                   ;; #+HUGO_CATEGORIES are used to set the post
+                   ;; categories in Org files written for file-based
+                   ;; exports.  But for subtree-based exports, the
+                   ;; EXPORT_HUGO_CATEGORIES property can be used to
+                   ;; override inherited categories and Org-style
+                   ;; categories (Org-style tags with "@" prefix).
+
                    ;; title
                    ;; "title" is parsed from the Org #+TITLE or the subtree heading.
                    ;; type
@@ -1184,7 +1190,7 @@ INFO is a plist holding export options."
                 ;; property values.
                 (widen)
                 (ignore-errors ;If the point is at beginning of buffer even after widening
-                 (backward-char))
+                  (backward-char))
                 ;; (message "[body filter DBG] line at pt: %s" (thing-at-point 'line))
                 (org-hugo--get-front-matter info))))
         (body (if (org-string-nw-p body) ;Insert extra newline if body is non-empty
@@ -1392,7 +1398,7 @@ Example: :some__tag:   -> \"some tag\"."
   "Wrapper function for `org-hugo--transform-org-tags'.
 
 1. Convert the input TAG-STR string to a list,
-2. Passe that to `org-hugo--transform-org-tags', and
+2. Pass that to `org-hugo--transform-org-tags', and
 3. Convert the returned list back to a string, with elements
    separated by `org-hugo--internal-tag-separator'.
 4. Return that string.
@@ -1499,31 +1505,40 @@ INFO is a plist used as a communication channel."
          (all-t-and-c-str (org-entry-get (point) "ALLTAGS"))
          (all-t-and-c (when (stringp all-t-and-c-str)
                         (org-split-string all-t-and-c-str ":")))
-         (tags-list (cl-remove-if #'org-hugo--category-p all-t-and-c))
-         (tags-list (org-hugo--transform-org-tags tags-list info))
-         (tags (org-string-nw-p ;Don't allow tags to be just whitespace
-                (or (org-string-nw-p (mapconcat #'identity
-                                                tags-list
-                                                org-hugo--internal-tag-separator))
-                    (let ((merged-tags (concat
-                                        (let ((tags1 (plist-get info :hugo-tags)))
-                                          (when tags1
-                                            tags1)) " "
-                                        (let ((tags2 (plist-get info :tags)))
-                                          (when tags2
-                                            tags2)))))
-                      (org-hugo--transform-org-tags-str merged-tags info :no-prefer-hyphen)))))
-         (categories-list (cl-remove-if-not #'org-hugo--category-p all-t-and-c))
-         (categories-list (org-hugo--transform-org-tags categories-list info))
-         (categories (or (org-string-nw-p
-                          (mapconcat (lambda (str)
-                                       ;; Remove "@" from beg of categories.
-                                       (replace-regexp-in-string "\\`@" "" str))
-                                     categories-list
-                                     org-hugo--internal-tag-separator))
-                         (org-hugo--transform-org-tags-str
-                          (plist-get info :hugo-categories)
-                          info :no-prefer-hyphen)))
+         (tags (org-string-nw-p ;Don't allow tags to be just whitespace.
+                (or
+                 ;; Look for tags set using #+HUGO_TAGS keyword, or
+                 ;; EXPORT_HUGO_TAGS property if available.
+                 (org-hugo--transform-org-tags-str
+                  (plist-get info :hugo-tags) info :no-prefer-hyphen)
+                 ;; Else use Org tags (the ones set in headlines
+                 ;; and/or inherited) if any.
+                 (let* ((tags-list (cl-remove-if #'org-hugo--category-p all-t-and-c))
+                        (tags-list (org-hugo--transform-org-tags tags-list info)))
+                   ;; (when tags-list
+                   ;;   (message "[get fm DBG] tags: tags-list = %s" tags-list))
+                   (org-string-nw-p (mapconcat #'identity
+                                               tags-list
+                                               org-hugo--internal-tag-separator))))))
+         (categories (or
+                      ;; Look for categories set using
+                      ;; #+HUGO_CATEGORIES keyword, or
+                      ;; EXPORT_HUGO_CATEGORIES property if available.
+                      (org-hugo--transform-org-tags-str
+                       (plist-get info :hugo-categories) info :no-prefer-hyphen)
+                      ;; Else use categories set using Org tags with
+                      ;; "@" prefix (the ones set in headlines and/or
+                      ;; inherited) if any.
+                      (let* ((categories-list (cl-remove-if-not #'org-hugo--category-p all-t-and-c))
+                             (categories-list (org-hugo--transform-org-tags categories-list info)))
+                        ;; (when categories-list
+                        ;;   (message "dbg: categories: categories-list = %s" categories-list))
+                        (org-string-nw-p
+                         (mapconcat (lambda (str)
+                                      ;; Remove "@" from beg of categories.
+                                      (replace-regexp-in-string "\\`@" "" str))
+                                    categories-list
+                                    org-hugo--internal-tag-separator)))))
          (weight (let* ((wt (plist-get info :hugo-weight))
                         (auto-calc (and (stringp wt)
                                         (string= wt "auto")
@@ -1572,14 +1587,9 @@ INFO is a plist used as a communication channel."
                  (blackfriday . ,blackfriday)
                  (menu . ,menu-alist)))
          (data `,(append data custom-fm-data)))
-    ;; (when tags-list
-    ;; (message "[get fm DBG] tags: tags-list = %s" tags-list))
     ;; (message "[get fm DBG] tags: %s" tags)
-    ;; (when categories-list
-    ;;   (message "dbg: categories: categories-list = %s" categories-list))
     ;; (message "dbg: todo-state: keyword=%S draft=%S" todo-keyword draft)
     ;; (message "dbg: hugo tags: %S" (plist-get info :hugo-tags))
-    ;; (message "dbg: tags: %S" (plist-get info :tags))
     ;; (message "[get fm info DBG] %S" info)
     ;; (message "[get fm blackfriday DBG] %S" blackfriday)
     ;; (message "[get fm menu DBG] %S" menu-alist)
@@ -1757,7 +1767,6 @@ are \"toml\" and \"yaml\"."
                      "KEYWORDS"
                      "HUGO_MARKUP"
                      "HUGO_OUTPUTS"
-                     "TAGS"
                      "HUGO_TAGS"
                      "HUGO_CATEGORIES"
                      "HUGO_TYPE"

test/site/content-org/all-posts.org

@@ -27,10 +27,7 @@ Export this *first* post only by bringing point here and doing =M-x org-hugo-exp
 This post has no date.
 
 Export this *second* post only by bringing point here and doing =M-x org-hugo-export-subtree-to-md=.
-* Image
-:PROPERTIES:
-:EXPORT_TAGS: image
-:END:
+* Image                                                               :image:
 ** Image links
 :PROPERTIES:
 :EXPORT_FILE_NAME: image-links

test/site/content-org/single-posts/post-draft.org

@@ -6,7 +6,7 @@
 #+HUGO_BASE_DIR: ../../
 
 #+HUGO_SECTION: singles
-#+TAGS: single toml
+#+HUGO_TAGS: single toml
 #+HUGO_CATEGORIES: cat1 cat2
 #+HUGO_MENU: :menu "foo" :weight 10 :parent main
 

test/site/content-org/single-posts/post-toml.org

@@ -5,7 +5,7 @@
 
 #+HUGO_BASE_DIR: ../../
 #+HUGO_SECTION: singles
-#+TAGS: single toml
+#+HUGO_TAGS: single toml
 #+HUGO_CATEGORIES: cat1 cat2
 #+HUGO_MENU: :menu "foo" :weight 10 :parent main :identifier single-toml
 

test/site/content-org/single-posts/post-yaml.org

@@ -7,7 +7,7 @@
 #+HUGO_FRONT_MATTER_FORMAT: yaml
 
 #+HUGO_SECTION: singles
-#+TAGS: single yaml
+#+HUGO_TAGS: single yaml
 #+HUGO_CATEGORIES: cat1 cat2
 #+HUGO_MENU: :menu "foo" :weight 10 :parent main :identifier single-yaml
 

test/site/content-org/tags-and-categories.org

@@ -0,0 +1,46 @@
+#+TITLE: My Blog
+#+HUGO_BASE_DIR: ../
+
+#+TAGS: these tags do not get globally applied to the posts
+
+#+FILETAGS: alpha beta
+#+FILETAGS: hyphened-tag
+
+# Categories
+#+FILETAGS: @cat1
+
+# All tags in above #+FILETAGS lines will get collected.
+
+# 1. Load `ox-hugo'
+# 2. C-c C-e H A
+
+* Super headline                                                      :super:
+** Inheriting tags                             :gamma:delta:two__words:@cat2:
+:PROPERTIES:
+:EXPORT_FILE_NAME: inheriting-tags
+:END:
+If user specifies tags to the post subtree headline, those tags get
+added to the set of default tags set in =#+FILETAGS= (and the ones
+inherited). For the inheritance of tags from parent headlines and
+=#+FILETAGS= to work, =org-use-tag-inheritance= needs to be set
+appropriately if changed from the default value of =t=. These tags are
+collected together and assigned to the Hugo =tags= front matter
+variable for this post.
+
+When setting categories via Org-style tags, prefix the tags with
+"@". That "@" is used as a special character for =ox-hugo= to identify
+those tags to be used as Hugo categories. This applies to categories
+added as Org tags to headlines as well as =#+FILETAGS=.
+** Overriding Org-style tags       :this_tag_wont_apply:@this_cat_wont_apply:
+:PROPERTIES:
+:EXPORT_HUGO_TAGS: overriding
+:EXPORT_HUGO_TAGS+: underscore_is_retained hyphenated-works
+:EXPORT_HUGO_CATEGORIES: cat3 3__word__cat
+:EXPORT_FILE_NAME: overriding-tags
+:END:
+By using =EXPORT_HUGO_TAGS= in the property drawer, Org tags in the
+current headline ("this_tag_wont_apply") *and* the inherited one
+("alpha", "beta", "hyphenated-tag", "super") will get overridden.
+
+When setting categories via the keyword =#+HUGO+CATEGORIES= or the
+subtree property =EXPORT_HUGO_CATEGORIES=, do *not* add the "@" prefix.

test/site/content-org/tags-keyword.org

@@ -1,25 +0,0 @@
-#+TITLE: My Blog
-#+HUGO_BASE_DIR: ../
-#+TAGS: alpha beta
-#+TAGS: hyphened-tag
-
-# 1. Load `ox-hugo'
-# 2. C-c C-e H A
-
-* Overriding default tags
-:PROPERTIES:
-:EXPORT_TAGS: foo
-:EXPORT_FILE_NAME: tags-post-1
-:END:
-By using =EXPORT_TAGS= in the property drawer, the default set of
-tags set in =#+TAGS= is overridden.
-* Specifying additional tags
-:PROPERTIES:
-:EXPORT_HUGO_TAGS: gamma delta
-:EXPORT_HUGO_TAGS+: two__words
-:EXPORT_FILE_NAME: tags-post-2
-:END:
-If user specifies =EXPORT_HUGO_TAGS= in the property drawer, those
-tags get added to the set of default tags set in =#+TAGS= (if
-any).  These tags are collected together and assigned to the Hugo
-=tags= front matter variable.

test/site/content/posts/inheriting-tags.md

@@ -0,0 +1,19 @@
++++
+title = "Inheriting tags"
+tags = ["hyphened-tag", "alpha", "beta", "super", "gamma", "delta", "two words"]
+categories = ["cat1", "cat2"]
+draft = false
++++
+
+If user specifies tags to the post subtree headline, those tags get
+added to the set of default tags set in `#+FILETAGS` (and the ones
+inherited). For the inheritance of tags from parent headlines and
+`#+FILETAGS` to work, `org-use-tag-inheritance` needs to be set
+appropriately if changed from the default value of `t`. These tags are
+collected together and assigned to the Hugo `tags` front matter
+variable for this post.
+
+When setting categories via Org-style tags, prefix the tags with
+"@". That "@" is used as a special character for `ox-hugo` to identify
+those tags to be used as Hugo categories. This applies to categories
+added as Org tags to headlines as well as `#+FILETAGS`.

test/site/content/posts/overriding-tags.md

@@ -0,0 +1,13 @@
++++
+title = "Overriding Org-style tags"
+tags = ["overriding", "underscore_is_retained", "hyphenated-works"]
+categories = ["cat3", "3 word cat"]
+draft = false
++++
+
+By using `EXPORT_HUGO_TAGS` in the property drawer, Org tags in the
+current headline ("this\_tag\_wont\_apply") **and** the inherited one
+("alpha", "beta", "hyphenated-tag", "super") will get overridden.
+
+When setting categories via the keyword `#+HUGO+CATEGORIES` or the
+subtree property `EXPORT_HUGO_CATEGORIES`, do **not** add the "@" prefix.

test/site/content/posts/tags-post-1.md

@@ -1,8 +0,0 @@
-+++
-title = "Overriding default tags"
-tags = ["foo"]
-draft = false
-+++
-
-By using `EXPORT_TAGS` in the property drawer, the default set of
-tags set in `#+TAGS` is overridden.

test/site/content/posts/tags-post-2.md

@@ -1,10 +0,0 @@
-+++
-title = "Specifying additional tags"
-tags = ["gamma", "delta", "two words", "alpha", "beta", "hyphened-tag"]
-draft = false
-+++
-
-If user specifies `EXPORT_HUGO_TAGS` in the property drawer, those
-tags get added to the set of default tags set in `#+TAGS` (if
-any).  These tags are collected together and assigned to the Hugo
-`tags` front matter variable.