Skip to content

Commit

Permalink
Document "Dates"
Browse files Browse the repository at this point in the history 
Fixes #127
  • Loading branch information
@kaushalmodi
kaushalmodi committed Feb 6, 2018
1 parent 576e88b commit 14c005f
Show file tree
Hide file tree
Showing 2 changed files with 174 additions and 40 deletions.
191 changes: 156 additions & 35 deletions doc/ox-hugo-manual.org
View file
Expand Up @@ -42,7 +42,7 @@
- Similarly, support =#+attr_html= and =#+attr_css= for paragraphs,
example blocks, source blocks, plain lists and quote blocks too --
{{{issue(113)}}}.
- Now =publishdate= and =expirydate= front-matter properties get
- Now =publishDate= and =expiryDate= front-matter properties get
auto-derived from =SCHEDULED= and =DEADLINE= special properties if
associated with the valid Hugo post subtree --
{{{commit(0807f42d)}}}.
Expand Down Expand Up @@ -818,51 +818,53 @@ subtree* i.e. an Org subtree that has the =EXPORT_FILE_NAME= property
set.
#+caption: Hugo front-matter translation for subtree-based exports
#+attr_html: :class sane-table
|-------------------------------------------+----------------------------------------+----------------------------------------------------------------------------|
| Hugo front-matter (TOML) | Org | Org description |
|-------------------------------------------+----------------------------------------+----------------------------------------------------------------------------|
| =title = "foo"= | =* foo= | Subtree heading |
| =date = 2017-09-11T14:32:00-04:00= | =CLOSED: [2017-09-11 Mon 14:32]= | Auto-inserted =CLOSED= subtree property when switch to Org *DONE* state |
| =date = 2017-07-24= | =:EXPORT_DATE: 2017-07-24= | Subtree property |
| =publishdate = 2018-01-26T00:00:00-05:00= | =SCHEDULED: <2018-01-26 Fri>= | Auto-inserted =SCHEDULED= subtree property using default =C-c C-s= binding |
| =publishdate = 2018-01-26T00:00:00-05:00= | =:EXPORT_HUGO_PUBLISHDATE: 2018-01-26:= | Subtree property |
| =expirydate = 2999-01-01T00:00:00-05:00= | =DEADLINE: <2999-01-01 Tue>= | Auto-inserted =DEADLINE= subtree property using default =C-c C-d= binding |
| =expirydate = 2999-01-01T00:00:00-05:00= | =:EXPORT_HUGO_EXPIRYDATE: 2999-01-01:= | Subtree property |
| =lastmod = <current date>= | =:EXPORT_HUGO_AUTO_SET_LASTMOD: t= | Subtree property |
| =lastmod = <current date>= | =#+hugo_auto_set_lastmod: t= | Org keyword |
| =tags = ["toto", "zulu"]= | =* foo :toto:zulu:= | Subtree heading tags |
| =categories = ["x", "y"]= | =* foo :@x:@y:= | Subtree heading tags with =@= prefix |
| =draft = true= | =* TODO foo= | Subtree heading Org Todo state set to =TODO= (or =DRAFT=) |
| =draft = false= | =* foo= | Subtree heading Org Todo state *not* set to =TODO= (or =DRAFT=) |
| =weight = 123= | =:EXPORT_HUGO_WEIGHT: auto= | When set to =auto=, weight is auto-calculated |
| =weight = 123= (in =[menu.foo]=) | =:EXPORT_HUGO_MENU: :menu foo= | Menu weight is auto-calculated unless specified |
|-------------------------------------------+----------------------------------------+----------------------------------------------------------------------------|
|------------------------------------+----------------------------------------+----------------------------------------------------------------------------|
| Hugo front-matter (TOML) | Org | Org description |
|------------------------------------+----------------------------------------+----------------------------------------------------------------------------|
| =title = "foo"= | =* foo= | Subtree heading |
| =date = 2017-09-11T14:32:00-04:00= | =CLOSED: [2017-09-11 Mon 14:32]= | Auto-inserted =CLOSED= subtree property when switch to Org *DONE* state |
| =date = 2017-07-24= | =:EXPORT_DATE: 2017-07-24= | Subtree property |
| =publishDate = 2018-01-26= | =SCHEDULED: <2018-01-26 Fri>= | Auto-inserted =SCHEDULED= subtree property using default =C-c C-s= binding |
| =publishDate = 2018-01-26= | =:EXPORT_HUGO_PUBLISHDATE: 2018-01-26:= | Subtree property |
| =expiryDate = 2999-01-01= | =DEADLINE: <2999-01-01 Tue>= | Auto-inserted =DEADLINE= subtree property using default =C-c C-d= binding |
| =expiryDate = 2999-01-01= | =:EXPORT_HUGO_EXPIRYDATE: 2999-01-01:= | Subtree property |
| =lastmod = <current date>= | =:EXPORT_HUGO_AUTO_SET_LASTMOD: t= | Subtree property |
| =lastmod = <current date>= | =#+hugo_auto_set_lastmod: t= | Org keyword |
| =tags = ["toto", "zulu"]= | =* foo :toto:zulu:= | Subtree heading tags |
| =categories = ["x", "y"]= | =* foo :@x:@y:= | Subtree heading tags with =@= prefix |
| =draft = true= | =* TODO foo= | Subtree heading Org Todo state set to =TODO= (or =DRAFT=) |
| =draft = false= | =* foo= | Subtree heading Org Todo state *not* set to =TODO= (or =DRAFT=) |
| =weight = 123= | =:EXPORT_HUGO_WEIGHT: auto= | When set to =auto=, weight is auto-calculated |
| =weight = 123= (in =[menu.foo]=) | =:EXPORT_HUGO_MENU: :menu foo= | Menu weight is auto-calculated unless specified |
|------------------------------------+----------------------------------------+----------------------------------------------------------------------------|
***** Notes
- Precedence for =date= parsing: =CLOSED= subtree property /more than/
=EXPORT_DATE= subtree property /more than/ =#+date:= keyword.
**** For file-based exports
#+caption: Hugo front-matter translation for file-based exports
#+attr_html: :class sane-table
|-------------------------------------------+--------------------------------------|
| Hugo front-matter (TOML) | Org |
|-------------------------------------------+--------------------------------------|
| =title = "foo"= | =#+title: foo= |
| =date = 2017-07-24= | =#+date: 2017-07-24= |
| =publishdate = 2018-01-26T00:00:00-05:00= | =#+hugo_publishdate: 2018-01-26= |
| =expirydate = 2999-01-01T00:00:00-05:00= | =#+hugo_expirydate: 2999-01-01= |
| =lastmod = <current date>= | =#+hugo_auto_set_lastmod: t= |
| =tags = ["toto", "zulu"]= | =#+hugo_tags: toto zulu= |
| =categories = ["x", "y"]= | =#+hugo_categories: x y= |
| =draft = true= | =#+hugo_draft: true= |
| =draft = false= | =#+hugo_draft: false= (default) |
| =weight = 123= | =#+hugo_weight: 123= |
| =weight = 123= (in =[menu.foo]=) | =#+hugo_menu: :menu foo :weight 123= |
|-------------------------------------------+--------------------------------------|
|----------------------------------+--------------------------------------|
| Hugo front-matter (TOML) | Org |
|----------------------------------+--------------------------------------|
| =title = "foo"= | =#+title: foo= |
| =date = 2017-07-24= | =#+date: 2017-07-24= |
| =publishDate = 2018-01-26= | =#+hugo_publishdate: 2018-01-26= |
| =expiryDate = 2999-01-01= | =#+hugo_expirydate: 2999-01-01= |
| =lastmod = <current date>= | =#+hugo_auto_set_lastmod: t= |
| =tags = ["toto", "zulu"]= | =#+hugo_tags: toto zulu= |
| =categories = ["x", "y"]= | =#+hugo_categories: x y= |
| =draft = true= | =#+hugo_draft: true= |
| =draft = false= | =#+hugo_draft: false= (default) |
| =weight = 123= | =#+hugo_weight: 123= |
| =weight = 123= (in =[menu.foo]=) | =#+hugo_menu: :menu foo :weight 123= |
|----------------------------------+--------------------------------------|
***** Notes
- The auto weight calculation for posts and menu items works *only*
for subtree exports. For the file-based export flow, one needs to
specify the weights manually. The value of /weight/ set to ="auto"=
will be equivalent to /nil/ for the file-based export flow.
- See {{{doc(dates#org-hugo-date-format,=org-hugo-date-format=)}}} for
customizing the date formats for all /date/ front-matter parameters.
*** Formatting
:PROPERTIES:
:EXPORT_FILE_NAME: formatting
Expand All @@ -889,6 +891,125 @@ heading and how it exports to Markdown in [[https://raw.githubusercontent.com/ka
| =_underline_= | =<span class = "underline">underline</span>= |
| | - Requires *CSS* to render this =underline= class as an underline. |
|--------------------+--------------------------------------------------------------------|
*** Dates
:PROPERTIES:
:EXPORT_FILE_NAME: dates
:END:
**** Defcustoms
***** =org-hugo-date-format=
- Default value :: ="%Y-%m-%dT%T%z"=

This variable sets the date format used for exporting /date/
front-matter parameters like =date=, =publishDate=, =expiryDate=,
=lastmod=.

Note that the date format *must match* the date specification from
[[https://tools.ietf.org/html/rfc3339#section-5.8][RFC3339]].

Examples of RFC3339-compatible values for this variable:

|---------------------------+-----------------------------|
| Value | Example output |
|---------------------------+-----------------------------|
| =%Y-%m-%dT%T%z= (default) | =2017-07-31T17:05:38-04:00= |
| =%Y-%m-%dT%T= | =2017-07-31T17:05:38= |
| =%Y-%m-%d= | =2017-07-31= |
|---------------------------+-----------------------------|

Do =C-h v org-hugo-date-format= for more information (within Emacs,
once the =ox-hugo= package is loaded).
**** File-based Exports
:PROPERTIES:
:CUSTOM_ID: dates-file-based-exports
:END:
In Org files meant for file-based exports, you simply set a value for
a =#+hugo_FOO= keyword (in most cases, for example =#+date= is one of
the exceptions) to set the =FOO= parameter in the exported
front-matter.

#+caption: Dates translation from Org meta-data to Hugo front-matter (file-based exports)
#+attr_html: :class sane-table
|----------------------------------+----------------------------|
| Org | Hugo front-matter (TOML) |
|----------------------------------+----------------------------|
| =#+date: 2017-07-24= | =date = 2017-07-24= |
| =#+hugo_publishdate: 2018-01-26= | =publishDate = 2018-01-26= |
| =#+hugo_expirydate: 2999-01-01= | =expiryDate = 2999-01-01= |
| =#+hugo_lastmod: 2018-02-06= | =lastmod = 2018-02-06= |
| =#+hugo_auto_set_lastmod: t= | =lastmod = <current date>= |
|----------------------------------+----------------------------|
**** Subtree-based Exports
:PROPERTIES:
:CUSTOM_ID: dates-subtree-based-exports
:END:
The date meta-data can be set as Org properties in post subtrees,
similar to the keywords set for [[#dates-file-based-exports][File-based exports]]. But subtree-based
exports allow an even concise way to set those dates.
***** Date
This is interpreted from the Org [[https://orgmode.org/manual/Special-properties.html][Special Property]] =CLOSED=. This is
auto-set once the post-subtree's =TODO= state is set to =DONE= (~C-c
C-t~).

Here's an example:
#+begin_src org
,* DONE My post
CLOSED: [2018-01-23 Tue 14:10]
Post content.
#+end_src

Above gets translated to =date = 2018-01-23T14:10:00-05:00= in
front-matter (TOML).

/You do not then need to explicitly set the =:EXPORT_DATE:= property./
***** Publish Date
This is interpreted from the Org Special Property =SCHEDULED=. The
idea is that you schedule a task for a /future/ date, just as you
would set a post to be published in /future/. This property is
set using the default ~C-c C-s~ binding in Org.

Here's an example:
#+begin_src org
,* My future post
SCHEDULED: <2060-01-26 Mon>
Post content.
#+end_src

Above gets translated to =publishDate = 2060-01-26T00:00:00-05:00= in
front-matter (TOML).

/You do not then need to explicitly set the =:EXPORT_HUGO_PUBLISHDATE:=
property./
***** Expiry Date
This is interpreted from the Org Special Property =DEADLINE=. The idea
is that just as you /ideally/ don't plan to work on a task after a set
deadline, you don't plan to keep a post published after a set expiry
date. This property is set using the default ~C-c C-d~ binding in Org.

Here's an example:
#+begin_src org
,* My short-lived post
DEADLINE: <2018-02-06 Tue>
Post content.
#+end_src

Above gets translated to =expiryDate = 2018-02-06T00:00:00-05:00= in
front-matter (TOML).

/You do not then need to explicitly set the =:EXPORT_HUGO_EXPIRYDATE:=
property./
***** Last modified
Like any other front-matter property, you can explicitly set the /last
modified/ date too, using the =:EXPORT_HUGO_LASTMOD:= property.

But what's the point of calling a property /last modified/, if you
forget to manually update that property *each time* you update the
post. SO =ox-hugo= takes care of that for you.. if you set the property
=:EXPORT_HUGO_AUTO_SET_LASTMOD:= to a non-nil value.

It's normal for one to choose to auto-set the /last modified/ date for
all the posts. So instead of setting the above property for each post
individually, it might be more convenient to simply put
=#+hugo_auto_set_lastmod: t= at the top of the file.
*** Image Links
:PROPERTIES:
:EXPORT_FILE_NAME: image-links
Expand Down
23 changes: 18 additions & 5 deletions doc/static/css/style.css
View file
Expand Up @@ -126,14 +126,14 @@ figure a:hover {
/* Sane Table */
/* https://css-tricks.com/complete-guide-table-element/#article-header-id-17 */
.sane-table table {
border-collapse: collapse;
width: 100%;
border-collapse: collapse;
width: 100%;
}
.sane-table th,
.sane-table td {
padding: 0.25rem;
text-align: left;
border: 1px solid #ccc;
padding: 0.25rem;
text-align: left;
border: 1px solid #ccc;
}

/* TeX, LaTeX, XeTeX logo */
Expand All @@ -158,3 +158,16 @@ figure a:hover {
margin-left: -0.36em;
margin-right: -0.15em;
}

/* Description lists */
dt {
font-weight: bold;
}
dd {
margin-bottom: .5rem;
}

/* No list bullets in task lists */
ul.task-list {
list-style-type: none;
}

0 comments on commit 14c005f

Please sign in to comment.