wilderjds
/
ox-hugo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document "Dates"

Browse Source 
Fixes https://github.com/kaushalmodi/ox-hugo/issues/127
master
Kaushal Modi 8 years ago
parent 576e88bba5
commit 14c005f216
2 changed files with 174 additions and 40 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 191
      doc/ox-hugo-manual.org
  2. 23
      doc/static/css/style.css

191
doc/ox-hugo-manual.org
Unescape View File

@ -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)}}}.
@ -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
@ -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

23
doc/static/css/style.css vendored
Unescape View File

@ -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 */
@ -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;
}

Write Preview
Loading…
Cancel
Save