diff --git a/README.org b/README.org index 6a0af97..efc4304 100644 --- a/README.org +++ b/README.org @@ -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 = = | =: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 = = | =:EXPORT_HUGO_AUTO_SET_LASTMOD: t= | Subtree property | +| =lastmod = = | =#+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 = = | =#+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. diff --git a/doc/images/one-post-per-file.png b/doc/images/one-post-per-file.png index 7765c9e..fca4b50 100755 Binary files a/doc/images/one-post-per-file.png and b/doc/images/one-post-per-file.png differ diff --git a/doc/ox-hugo-manual.org b/doc/ox-hugo-manual.org index 8bb9229..8f48768 100644 --- a/doc/ox-hugo-manual.org +++ b/doc/ox-hugo-manual.org @@ -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 = = | =: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 = = | =:EXPORT_HUGO_AUTO_SET_LASTMOD: t= | Subtree property | +| =lastmod = = | =#+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 = = | =#+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 diff --git a/doc/ox-hugo.wiki b/doc/ox-hugo.wiki index caf810e..529927b 160000 --- a/doc/ox-hugo.wiki +++ b/doc/ox-hugo.wiki @@ -1 +1 @@ -Subproject commit caf810e426151d568b2312e156be21b860af1c54 +Subproject commit 529927bfaab53e5fae00afbcb36b7e7853603237 diff --git a/example-site/content-org/writing-hugo-blog-in-org-file-export.org b/example-site/content-org/writing-hugo-blog-in-org-file-export.org index 6d85202..38baf72 100644 --- a/example-site/content-org/writing-hugo-blog-in-org-file-export.org +++ b/example-site/content-org/writing-hugo-blog-in-org-file-export.org @@ -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=. diff --git a/example-site/content/writing-hugo-blog-in-org-file-export.md b/example-site/content/writing-hugo-blog-in-org-file-export.md index 5de35f3..280d3c8 100644 --- a/example-site/content/writing-hugo-blog-in-org-file-export.md +++ b/example-site/content/writing-hugo-blog-in-org-file-export.md @@ -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}