X-Git-Url: https://www.kengrimes.com/gitweb/?p=kengrimes.com%2Fcontent.git;a=blobdiff_plain;f=content%2Fox-hugo-tutorial.md;fp=content%2Fox-hugo-tutorial.md;h=4658738389240df2ce87ca271c62858935646fef;hp=c4210eb50a0668c0d70e4be9572ff057c16302e4;hb=ef2968208b0629b49479959703ca092e4e034816;hpb=c0683515ff9738eaabf6b9c93ea55d61deb33681 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.