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

Clarify differences in Org between file and subtree export flows

Browse Source 
Also fix the writing-hugo-blog-in-org-file-export.org.. we cannot have
auto-weight calculation in file export flow (compared to subtree
export flow).
master
Kaushal Modi 9 years ago
parent 899939cdc4
commit d04e96c396
6 changed files with 80 additions and 30 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. 44
      README.org
  2. BIN
      doc/images/one-post-per-file.png
  3. 44
      doc/ox-hugo-manual.org
  4. 2
      doc/ox-hugo.wiki
  5. 11
      example-site/content-org/writing-hugo-blog-in-org-file-export.org
  6. 9
      example-site/content/writing-hugo-blog-in-org-file-export.md

44
README.org
Unescape View File

@ -177,26 +177,50 @@ exported Markdown files.
5. Create an Org file in there and follow the *Usage* section in the
[[https://github.com/kaushalmodi/ox-hugo#usage][README]] or [[https://github.com/kaushalmodi/ox-hugo/wiki/Usage][Wiki]] to export it.
* Translation of Org meta-data to Hugo front-matter
** For subtree exports (=C-c C-e H H= or =C-c C-e H A=)
When organizing the posts as Org *subtrees*, many Hugo front-matter
variables get set implicitly using the meta-data parsed from the posts
in Org.
Below, where /subtree/ is mentioned, it implies a *valid Hugo-post
subtree* i.e. an Org subtree that has the =EXPORT_FILE_NAME= property
set.
|------------------------------------+------------------------------------+-------------------------------------------------------------------------|
| Hugo front-matter (TOML) | Org | Org description |
|------------------------------------+------------------------------------+-------------------------------------------------------------------------|
| =title = "foo"​= | =* foo= | Subtree heading (needs to have the =EXPORT_FILE_NAME= property set) |
| =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 (or =#+DATE:=) |
| =tags = ["abc", "def"]= | =* foo :abc:def:= | Heading tags |
| =categories = ["x", "y"]= | =* foo :@x:@y:= | Heading tags with =@= prefix |
| =draft = true= | =* TODO foo= | Heading set to =TODO= (or =DRAFT=) |
| =draft = false= | =* foo= | Heading *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. |
| =lastmod = <current date>= | =:EXPORT_HUGO_AUTO_SET_LASTMOD: t= | Subtree property (or =#+HUGO_AUTO_SET_LASTMODE: t=) |
| =date = 2017-07-24= | =:EXPORT_DATE: 2017-07-24= | Subtree property |
| =lastmod = <current date>= | =:EXPORT_HUGO_AUTO_SET_LASTMOD: t= | Subtree property |
| =lastmod = <current date>= | =#+HUGO_AUTO_SET_LASTMOD: t= | Org keyword |
| =tags = ["abc", "def"]= | =* foo :abc:def:= | 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
*** Notes
- Precedence for =date= parsing: =CLOSED= subtree property /more than/
=EXPORT_DATE= subtree property /more than/ =#+DATE:= keyword.
** For complete-file exports (=C-c C-e H h=)
|----------------------------------+--------------------------------------|
| Hugo front-matter (TOML) | Org |
|----------------------------------+--------------------------------------|
| =title = "foo"​= | =#+TITLE: foo= |
| =date = 2017-07-24= | =#+DATE: 2017-07-24= |
| =lastmod = <current date>= | =#+HUGO_AUTO_SET_LASTMOD: t= |
| =tags = ["abc", "def"]= | =#+HUGO_TAGS: abc def= |
| =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 complete-file export flow, one needs to
specify the weights manually if needed.
* Formatting
Below table shows the translation of Org markup to Markdown markup in
the exported =.md= files.

BIN
doc/images/one-post-per-file.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 194 KiB

After

Width:  |  Height:  |  Size: 201 KiB

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

@ -237,26 +237,50 @@ exported Markdown files.
:PROPERTIES:
:EXPORT_FILE_NAME: Org meta-data to Hugo front-matter
:END:
*** For subtree exports (=C-c C-e H H= or =C-c C-e H A=)
When organizing the posts as Org *subtrees*, many Hugo front-matter
variables get set implicitly using the meta-data parsed from the posts
in Org.
Below, where /subtree/ is mentioned, it implies a *valid Hugo-post
subtree* i.e. an Org subtree that has the =EXPORT_FILE_NAME= property
set.
|------------------------------------+------------------------------------+-------------------------------------------------------------------------|
| Hugo front-matter (TOML) | Org | Org description |
|------------------------------------+------------------------------------+-------------------------------------------------------------------------|
| =title = "foo"​= | =* foo= | Subtree heading (needs to have the =EXPORT_FILE_NAME= property set) |
| =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 (or =#+DATE:=) |
| =tags = ["abc", "def"]= | =* foo :abc:def:= | Heading tags |
| =categories = ["x", "y"]= | =* foo :@x:@y:= | Heading tags with =@= prefix |
| =draft = true= | =* TODO foo= | Heading set to =TODO= (or =DRAFT=) |
| =draft = false= | =* foo= | Heading *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. |
| =lastmod = <current date>= | =:EXPORT_HUGO_AUTO_SET_LASTMOD: t= | Subtree property (or =#+HUGO_AUTO_SET_LASTMODE: t=) |
| =date = 2017-07-24= | =:EXPORT_DATE: 2017-07-24= | Subtree property |
| =lastmod = <current date>= | =:EXPORT_HUGO_AUTO_SET_LASTMOD: t= | Subtree property |
| =lastmod = <current date>= | =#+HUGO_AUTO_SET_LASTMOD: t= | Org keyword |
| =tags = ["abc", "def"]= | =* foo :abc:def:= | 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
**** Notes
- Precedence for =date= parsing: =CLOSED= subtree property /more than/
=EXPORT_DATE= subtree property /more than/ =#+DATE:= keyword.
*** For complete-file exports (=C-c C-e H h=)
|----------------------------------+--------------------------------------|
| Hugo front-matter (TOML) | Org |
|----------------------------------+--------------------------------------|
| =title = "foo"​= | =#+TITLE: foo= |
| =date = 2017-07-24= | =#+DATE: 2017-07-24= |
| =lastmod = <current date>= | =#+HUGO_AUTO_SET_LASTMOD: t= |
| =tags = ["abc", "def"]= | =#+HUGO_TAGS: abc def= |
| =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 complete-file export flow, one needs to
specify the weights manually if needed.
** Formatting :wiki:
:PROPERTIES:
:EXPORT_FILE_NAME: Formatting

2
doc/ox-hugo.wiki

@ -1 +1 @@
Subproject commit caf810e426151d568b2312e156be21b860af1c54
Subproject commit 529927bfaab53e5fae00afbcb36b7e7853603237

11
example-site/content-org/writing-hugo-blog-in-org-file-export.org
Unescape View File

@ -1,7 +1,7 @@
#+HUGO_BASE_DIR: ../
#+HUGO_SECTION: ./
#+HUGO_WEIGHT: auto
#+HUGO_WEIGHT: 2001
#+HUGO_AUTO_SET_LASTMOD: t
#+TITLE: Writing Hugo blog in Org
@ -9,20 +9,21 @@
#+DATE: 2017-09-10
#+HUGO_TAGS: hugo org
#+HUGO_CATEGORIES: emacs
#+HUGO_MENU: :menu "main"
#+HUGO_MENU: :menu "main" :weight 2001
#+HUGO_CUSTOM_FRONT_MATTER: :foo bar :baz zoo :alpha 1 :beta "two words" :gamma 10
#+HUGO_DRAFT: true
* First heading within the post
* First heading within the post :foo:
- This post will be exported as
=content/posts/writing-hugo-blog-in-org-file-export.md=.
- Its title will be "Writing Hugo blog in Org".
- It will have /hugo/ and /org/ tags and /emacs/ as category.
- The menu item /weight/ and post /weight/ are auto-calculated.
- The menu item /identifier/ is auto-set.
- The /lastmod/ property in the front-matter is set automatically to
the time of export.
- The menu item /identifier/ is auto-set.
- The menu item /weight/ and post /weight/ if needed have to be
manually specified as shown above.
** A sub-heading under that heading
- It's draft state will be marked as =true= because of =#+HUGO_DRAFT:
true=.

9
example-site/content/writing-hugo-blog-in-org-file-export.md
Unescape View File

@ -1,7 +1,7 @@
+++
title = "Writing Hugo blog in Org"
date = 2017-09-10
lastmod = 2017-09-11T12:48:42-04:00
lastmod = 2017-09-11T16:49:39-04:00
tags = ["hugo", "org"]
categories = ["emacs"]
weight = 2001
@ -12,8 +12,8 @@ alpha = 1
beta = "two words"
gamma = 10
[menu.main]
weight = 2001
identifier = "writing-hugo-blog-in-org"
weight = 2001
+++
## First heading within the post {#first-heading-within-the-post}
@ -22,10 +22,11 @@ gamma = 10
`content/posts/writing-hugo-blog-in-org-file-export.md`.
- Its title will be "Writing Hugo blog in Org".
- It will have _hugo_ and _org_ tags and _emacs_ as category.
- The menu item _weight_ and post _weight_ are auto-calculated.
- The menu item _identifier_ is auto-set.
- The _lastmod_ property in the front-matter is set automatically to
the time of export.
- The menu item _identifier_ is auto-set.
- The menu item _weight_ and post _weight_ if needed have to be
manually specified as shown above.
### A sub-heading under that heading {#a-sub-heading-under-that-heading}

Write Preview
Loading…
Cancel
Save