Skip to content

Commit

Permalink
Fix: Don't change default interpretation of #+TAGS #breaking
Browse files Browse the repository at this point in the history
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/
=====
kaushalmodi committed Oct 29, 2017
1 parent 4a476d9 commit 30ac7c3
Showing 15 changed files with 401 additions and 90 deletions.
22 changes: 22 additions & 0 deletions README.org
Original file line number Diff line number Diff line change
@@ -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)
27 changes: 27 additions & 0 deletions doc/content/doc/changelog.md
Original file line number Diff line number Diff line change
@@ -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}


113 changes: 113 additions & 0 deletions doc/content/doc/tags-and-categories.md
Original file line number Diff line number Diff line change
@@ -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/)
108 changes: 108 additions & 0 deletions doc/ox-hugo-manual.org
Original file line number Diff line number Diff line change
@@ -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
Loading

0 comments on commit 30ac7c3

Please sign in to comment.