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
{{< /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
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}
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-<RIGHT>` (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-<RIGHT>` (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}
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.
projects / kengrimes.com / content.git / blobdiff