From ef2968208b0629b49479959703ca092e4e034816 Mon Sep 17 00:00:00 2001 From: kengrimes Date: Fri, 20 Apr 2018 13:47:07 -0700 Subject: [PATCH] ox-hugo tutorial updates, theme updated with EXPORT_DESCRIPTION instead of custom front-matter --- config.toml | 2 +- content.org | 101 ++++++++++++++++++++---------------- content/about/_index.md | 9 +++- content/forth/_index.md | 2 +- content/ox-hugo-tutorial.md | 86 ++++++++++++++++-------------- content/ox-hugo.md | 2 +- 6 files changed, 114 insertions(+), 88 deletions(-) diff --git a/config.toml b/config.toml index e696d9a..57bcf54 100644 --- a/config.toml +++ b/config.toml @@ -1,4 +1,4 @@ -baseURL = "https://www.kengrimes.com" +baseURL = "https://krull.kengrimes.com/webtest" languageCode = "en-us" buildDrafts = true title = "Ken Grimes" diff --git a/content.org b/content.org index 37aa9a4..9de9616 100644 --- a/content.org +++ b/content.org @@ -201,7 +201,8 @@ the index, as a sub-heading of the section definition (which merely specifies which sub-directory the content will output to). To illustrate, let's assume you want to extend the previous site definition with -a section about fishsticks. +a section about fishsticks. We'll do this the "wrong way" first to show how Org +handles inheritence: #+begin_src org -n 24 ,* Fishsticks :PROPERTIES: @@ -222,7 +223,7 @@ If this is fish, I'll be a monkey's uncle. I think these gave me the herpes. #+end_src In this example, we've defined the main homepage of the section inside the -tier-1 heading for Fishsticks. This is technically valid, and produces the +tier-1 heading for Fishsticks. This is /technically/ valid, and produces the expected file output: #+begin_src . @@ -277,32 +278,43 @@ If this is fish, I'll be a monkey's uncle. I think these gave me the herpes. #+end_src -Tisk tisk. So be sure to put your index pages in subheadings (just as you do -with normal pages) so that the tier-1 heading can be used for "global" -definitions that affect all of the pages. A corrected section for fishsticks -would look like this: -#+begin_src org -n 25 -,** Fishsticks +This explains the flexibility of ox-hugo's straightforward parsing +rules. Specifically, that any headings with an ~:EXPORT_FILE_NAME:~ tag will +export everything beneath them as content. The content organization in this +erroneous example duplicates data, but might still be useful if you wanted to +create, for instance, an "all_content" page for the section. In general, though, +be sure to put your index pages in subheadings (just as you do with normal +pages) so that the tier-1 heading can be used for "global" definitions that +affect all of the pages. A /correct/ section for fishsticks should look like +this: +#+begin_src org -n 24 +,* Fishsticks :PROPERTIES: :EXPORT_HUGO_SECTION: fishsticks :END: -,*** Fishsticks Home +,** Fishsticks Home :PROPERTIES: :EXPORT_HUGO_MENU: :menu "main" :EXPORT_FILE_NAME: _index :END: This section devoted to Orson Wells, R.I.P. -,*** Van De Camps +,** Van De Camps :PROPERTIES: :EXPORT_FILE_NAME: van-de-camps :END: If this is fish, I'll be a monkey's uncle. -,*** Gortons +,** Gortons :PROPERTIES: :EXPORT_FILE_NAME: gortons :END: I think these gave me the herpes. #+end_src +Now the homepage for the fishsticks section has a heading all its own, just like +any other page. That's better! Now our homepage will output the content only +from its subheading, and the other pages don't inherit the homepage's +properties. All pages inherit the ~:EXPORT_HUGO_SECTION: fishsticks~ property +though, which is what we want to ensure that these pages are exported to the +proper section. *** Hugo Setup At this point, setting up Hugo and publishing is simple. [[https://gohugo.io/getting-started/installing/][Installing]] Hugo is @@ -590,37 +602,23 @@ Org Capture. **** Drafts and Automatic Timestamps By default, Hugo will not build any markdown files whose front-matter properties include ~draft: true~. This is very convenient for in-progress posts that you -leave in your Org file, or in the *content/* directory. If you are using -archetypes (which define default front-matter for various resource types, and -may include Hugo templating directives), you can see that the primary archetype -in *archetypes/default.md* set the draft property to true on all content unless -the markdown file overrides this behavior: -#+begin_src markdown ---- -title: "{{ replace .Name "-" " " | title }}" -date: {{ .Date }} -draft: true ---- -#+end_src +leave in your Org file, or in the *content/* directory. + +Ox-hugo will always fill out the draft property, and by default every exported +header will have its draft property set to *false*. However, ox-hugo also links +this behavior to the TODO feature of Org. When you cycle a heading's TODO value +with ~S-~ (that's Shift + Right Arrow Key), you will signal to ox-hugo to +export this heading as a draft (i.e. ~draft: true~), which will prevent Hugo +from building it into an HTML page. -Ox-hugo will always fill out the draft property, overriding this archetype's -default value. By default, every exported header will have its draft property -set to *false*. However, ox-hugo conveniently links this behavior to the TODO -feature of Org. When you cycle a heading's TODO value with ~S-~ (that's -Shift + Right Arrow Key), you will signal to ox-hugo to export this heading as -a draft (i.e. ~draft: true~), which will prevent Hugo from building it into an -HTML page. - -Better still, when a heading is cycled to the DONE state in Org, it will -automatically generate a timestamp for when the heading was closed. Ox-hugo will -export DONE headings with ~draft: false~ and, better still, will use Org's -timestamp to fill out the Date property in the markdown file. This makes it -trivial to manage writing multiple posts at once, and automatically timestamp -completion dates. +When a heading is cycled to the DONE state in Org, it will automatically +generate a timestamp for when the heading was closed. Ox-hugo will export DONE +headings with ~draft: false~ and, better still, will use Org's timestamp to fill +out the Date property in the markdown file. This makes it trivial to manage +writing multiple posts at once, and automatically timestamp completion dates. You may also explicitly set this date parameter with the ~:EXPORT_DATE:~ -property, but the convenience of using DONE-state switching is pretty hard to -pass up. +property, but the ease of using DONE-state switching is pretty hard to pass up. **** Renaming Tags and Other Properties If a theme you are using has any idiosyncrasies about your naming conventions @@ -644,13 +642,20 @@ This is the description, but will export as the Summary value in front-matter To do this on a per-heading basis, simply add the ~:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE:~ property to a heading's property block, and the replacements will only occur within that heading. +*** Thanks +Thanks to Kaushal Modi, who found this article on the googs within days of me +posting it, for reaching out to me and providing thorough feedback and error +checking. + +And special thanks to me, for once again overcoming Hamhock the Laziness Demon +who has possessed me since birth and hates it when I do anything productive. ** DONE I did a blog :blog:org:emacs:hugo: CLOSED: [2018-04-06 Fri 18:29] :PROPERTIES: :EXPORT_FILE_NAME: ox-hugo -:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :heading "Exporting to Hugo's Blackfriday Markdown from Orgmode" -:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/org.png +:EXPORT_DESCRIPTION: "Exporting to Hugo's Blackfriday Markdown from Orgmode" +:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :header /img/org.png :END: ox-hugo is an [[http://en.wikipedia.org/wiki/Emacs][Emacs]] package for [[http://en.wikipedia.org/wiki/org-mode][Org mode]] that produces input for the static content generator [[https://gohugo.io/][Hugo]], which I use for this website. Today I integrated its @@ -668,8 +673,8 @@ information I come across and publish it within seconds. Now I have no excuses! :EXPORT_FILE_NAME: _index :EXPORT_HUGO_MENU: :menu "main" :EXPORT_HUGO_SECTION: forth -:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :heading "Highly Factored Code" -:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/forth.png +:EXPORT_DESCRIPTION: "Highly Factored Code" +:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :header /img/forth.png :END: This is where I post my watForth programs. @@ -691,10 +696,16 @@ At present, my forth testbed is located at https://forth.kengrimes.com :PROPERTIES: :EXPORT_HUGO_SECTION: about :EXPORT_HUGO_MENU: :menu "main" :title About -:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :heading '("Ken Grimes" "Computer Scientist" "At Large") -:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/home.png +:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :header /img/home.png :EXPORT_FILE_NAME: _index :END: +#+begin_description +Ken Grimes + +Computer Scientist + +At Large +#+end_description Hi! I'm Ken, a 34-year-old computer scientist currently living in Irvine, California. This is a website I've constructed for the purpose of developing web-facing software. I will probably blog with it once development is diff --git a/content/about/_index.md b/content/about/_index.md index 9472f3d..f978e63 100644 --- a/content/about/_index.md +++ b/content/about/_index.md @@ -1,8 +1,15 @@ --- title: "About" author: ["Ken Grimes"] +description: > + Ken Grimes + + + Computer Scientist + + + At Large draft: false -heading: ["Ken Grimes", "Computer Scientist", "At Large"] header: "/img/home.png" menu: main: diff --git a/content/forth/_index.md b/content/forth/_index.md index 36aa590..1ea2da4 100644 --- a/content/forth/_index.md +++ b/content/forth/_index.md @@ -1,8 +1,8 @@ --- title: "Forth" author: ["Ken Grimes"] +description: "Highly Factored Code" draft: false -heading: "Highly Factored Code" header: "/img/forth.png" menu: main: diff --git a/content/ox-hugo-tutorial.md b/content/ox-hugo-tutorial.md index c4210eb..4658738 100644 --- a/content/ox-hugo-tutorial.md +++ b/content/ox-hugo-tutorial.md @@ -210,7 +210,8 @@ the index, as a sub-heading of the section definition (which merely specifies which sub-directory the content will output to). To illustrate, let's assume you want to extend the previous site definition with -a section about fishsticks. +a section about fishsticks. We'll do this the "wrong way" first to show how Org +handles inheritence: {{< highlight org "linenos=table, linenostart=24" >}} * Fishsticks @@ -233,7 +234,7 @@ I think these gave me the herpes. {{< /highlight >}} In this example, we've defined the main homepage of the section inside the -tier-1 heading for Fishsticks. This is technically valid, and produces the +tier-1 heading for Fishsticks. This is _technically_ valid, and produces the expected file output: ```nil @@ -294,34 +295,46 @@ If this is fish, I'll be a monkey's uncle. I think these gave me the herpes. {{< /highlight >}} -Tisk tisk. So be sure to put your index pages in subheadings (just as you do -with normal pages) so that the tier-1 heading can be used for "global" -definitions that affect all of the pages. A corrected section for fishsticks -would look like this: +This explains the flexibility of ox-hugo's straightforward parsing +rules. Specifically, that any headings with an `:EXPORT_FILE_NAME:` tag will +export everything beneath them as content. The content organization in this +erroneous example duplicates data, but might still be useful if you wanted to +create, for instance, an "all\_content" page for the section. In general, though, +be sure to put your index pages in subheadings (just as you do with normal +pages) so that the tier-1 heading can be used for "global" definitions that +affect all of the pages. A _correct_ section for fishsticks should look like +this: -{{< highlight org "linenos=table, linenostart=25" >}} -** Fishsticks +{{< highlight org "linenos=table, linenostart=24" >}} +* Fishsticks :PROPERTIES: :EXPORT_HUGO_SECTION: fishsticks :END: -*** Fishsticks Home +** Fishsticks Home :PROPERTIES: :EXPORT_HUGO_MENU: :menu "main" :EXPORT_FILE_NAME: _index :END: This section devoted to Orson Wells, R.I.P. -*** Van De Camps +** Van De Camps :PROPERTIES: :EXPORT_FILE_NAME: van-de-camps :END: If this is fish, I'll be a monkey's uncle. -*** Gortons +** Gortons :PROPERTIES: :EXPORT_FILE_NAME: gortons :END: I think these gave me the herpes. {{< /highlight >}} +Now the homepage for the fishsticks section has a heading all its own, just like +any other page. That's better! Now our homepage will output the content only +from its subheading, and the other pages don't inherit the homepage's +properties. All pages inherit the `:EXPORT_HUGO_SECTION: fishsticks` property +though, which is what we want to ensure that these pages are exported to the +proper section. + # Hugo Setup {#hugo-setup} @@ -636,38 +649,23 @@ Org Capture. By default, Hugo will not build any markdown files whose front-matter properties include `draft: true`. This is very convenient for in-progress posts that you -leave in your Org file, or in the **content/** directory. If you are using -archetypes (which define default front-matter for various resource types, and -may include Hugo templating directives), you can see that the primary archetype -in **archetypes/default.md** set the draft property to true on all content unless -the markdown file overrides this behavior: +leave in your Org file, or in the **content/** directory. -```markdown ---- -title: "{{ replace .Name "-" " " | title }}" -date: {{ .Date }} -draft: true ---- -``` +Ox-hugo will always fill out the draft property, and by default every exported +header will have its draft property set to **false**. However, ox-hugo also links +this behavior to the TODO feature of Org. When you cycle a heading's TODO value +with `S-` (that's Shift + Right Arrow Key), you will signal to ox-hugo to +export this heading as a draft (i.e. `draft: true`), which will prevent Hugo +from building it into an HTML page. -Ox-hugo will always fill out the draft property, overriding this archetype's -default value. By default, every exported header will have its draft property -set to **false**. However, ox-hugo conveniently links this behavior to the TODO -feature of Org. When you cycle a heading's TODO value with `S-` (that's -Shift + Right Arrow Key), you will signal to ox-hugo to export this heading as -a draft (i.e. `draft: true`), which will prevent Hugo from building it into an -HTML page. - -Better still, when a heading is cycled to the DONE state in Org, it will -automatically generate a timestamp for when the heading was closed. Ox-hugo will -export DONE headings with `draft: false` and, better still, will use Org's -timestamp to fill out the Date property in the markdown file. This makes it -trivial to manage writing multiple posts at once, and automatically timestamp -completion dates. +When a heading is cycled to the DONE state in Org, it will automatically +generate a timestamp for when the heading was closed. Ox-hugo will export DONE +headings with `draft: false` and, better still, will use Org's timestamp to fill +out the Date property in the markdown file. This makes it trivial to manage +writing multiple posts at once, and automatically timestamp completion dates. You may also explicitly set this date parameter with the `:EXPORT_DATE:` -property, but the convenience of using DONE-state switching is pretty hard to -pass up. +property, but the ease of using DONE-state switching is pretty hard to pass up. ## Renaming Tags and Other Properties {#renaming-tags-and-other-properties} @@ -697,3 +695,13 @@ This is the description, but will export as the Summary value in front-matter To do this on a per-heading basis, simply add the `:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE:` property to a heading's property block, and the replacements will only occur within that heading. + + +# Thanks {#thanks} + +Thanks to Kaushal Modi, who found this article on the googs within days of me +posting it, for reaching out to me and providing thorough feedback and error +checking. + +And special thanks to me, for once again overcoming Hamhock the Laziness Demon +who has possessed me since birth and hates it when I do anything productive. diff --git a/content/ox-hugo.md b/content/ox-hugo.md index f721686..514dd8b 100644 --- a/content/ox-hugo.md +++ b/content/ox-hugo.md @@ -1,10 +1,10 @@ --- title: "I did a blog" author: ["Ken Grimes"] +description: "Exporting to Hugo's Blackfriday Markdown from Orgmode" date: 2018-04-06T18:29:00-07:00 tags: ["blog", "org", "emacs", "hugo"] draft: false -heading: "Exporting to Hugo's Blackfriday Markdown from Orgmode" header: "/img/org.png" --- -- 2.18.0