From 30ac7c3351bc137fd6d424e05d347792feec30b9 Mon Sep 17 00:00:00 2001 From: Kaushal Modi Date: Sun, 29 Oct 2017 02:02:24 -0400 Subject: [PATCH] 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 | 22 ++++ doc/content/doc/changelog.md | 27 +++++ doc/content/doc/tags-and-categories.md | 113 ++++++++++++++++++ doc/ox-hugo-manual.org | 108 +++++++++++++++++ ox-hugo.el | 89 +++++++------- test/site/content-org/all-posts.org | 5 +- .../content-org/single-posts/post-draft.org | 2 +- .../content-org/single-posts/post-toml.org | 2 +- .../content-org/single-posts/post-yaml.org | 2 +- test/site/content-org/tags-and-categories.org | 46 +++++++ test/site/content-org/tags-keyword.org | 25 ---- test/site/content/posts/inheriting-tags.md | 19 +++ test/site/content/posts/overriding-tags.md | 13 ++ test/site/content/posts/tags-post-1.md | 8 -- test/site/content/posts/tags-post-2.md | 10 -- 15 files changed, 401 insertions(+), 90 deletions(-) create mode 100644 doc/content/doc/tags-and-categories.md create mode 100644 test/site/content-org/tags-and-categories.org delete mode 100644 test/site/content-org/tags-keyword.org create mode 100644 test/site/content/posts/inheriting-tags.md create mode 100644 test/site/content/posts/overriding-tags.md delete mode 100644 test/site/content/posts/tags-post-1.md delete mode 100644 test/site/content/posts/tags-post-2.md diff --git a/README.org b/README.org index ba33c9e4..7eff9cc4 100644 --- a/README.org +++ b/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) diff --git a/doc/content/doc/changelog.md b/doc/content/doc/changelog.md index fa86a5db..2764f259 100644 --- a/doc/content/doc/changelog.md +++ b/doc/content/doc/changelog.md @@ -6,6 +6,33 @@ draft = false identifier = "changelog" +++ +## v0.4 <2017-10-28 Sat> {#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 <2017-10-24 Tue> {#v0-dot-3-dot-2} diff --git a/doc/content/doc/tags-and-categories.md b/doc/content/doc/tags-and-categories.md new file mode 100644 index 00000000..2015acee --- /dev/null +++ b/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/) diff --git a/doc/ox-hugo-manual.org b/doc/ox-hugo-manual.org index 4f1dceda..d4b50af5 100644 --- a/doc/ox-hugo-manual.org +++ b/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 diff --git a/ox-hugo.el b/ox-hugo.el index 6e2a45bf..73748cee 100644 --- a/ox-hugo.el +++ b/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" diff --git a/test/site/content-org/all-posts.org b/test/site/content-org/all-posts.org index 7a27f6cb..2085a3e4 100644 --- a/test/site/content-org/all-posts.org +++ b/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 diff --git a/test/site/content-org/single-posts/post-draft.org b/test/site/content-org/single-posts/post-draft.org index b60615c7..b8975690 100644 --- a/test/site/content-org/single-posts/post-draft.org +++ b/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 diff --git a/test/site/content-org/single-posts/post-toml.org b/test/site/content-org/single-posts/post-toml.org index 12e227ef..4f53f8f7 100644 --- a/test/site/content-org/single-posts/post-toml.org +++ b/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 diff --git a/test/site/content-org/single-posts/post-yaml.org b/test/site/content-org/single-posts/post-yaml.org index adf6edfe..7b8f9b78 100644 --- a/test/site/content-org/single-posts/post-yaml.org +++ b/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 diff --git a/test/site/content-org/tags-and-categories.org b/test/site/content-org/tags-and-categories.org new file mode 100644 index 00000000..7bc482e0 --- /dev/null +++ b/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. diff --git a/test/site/content-org/tags-keyword.org b/test/site/content-org/tags-keyword.org deleted file mode 100644 index a37a65e2..00000000 --- a/test/site/content-org/tags-keyword.org +++ /dev/null @@ -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. diff --git a/test/site/content/posts/inheriting-tags.md b/test/site/content/posts/inheriting-tags.md new file mode 100644 index 00000000..7ac981e3 --- /dev/null +++ b/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`. diff --git a/test/site/content/posts/overriding-tags.md b/test/site/content/posts/overriding-tags.md new file mode 100644 index 00000000..0130b4b5 --- /dev/null +++ b/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. diff --git a/test/site/content/posts/tags-post-1.md b/test/site/content/posts/tags-post-1.md deleted file mode 100644 index 1c5d64d0..00000000 --- a/test/site/content/posts/tags-post-1.md +++ /dev/null @@ -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. diff --git a/test/site/content/posts/tags-post-2.md b/test/site/content/posts/tags-post-2.md deleted file mode 100644 index b515b705..00000000 --- a/test/site/content/posts/tags-post-2.md +++ /dev/null @@ -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.