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:
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
.
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
**** 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-<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
If a theme you are using has any idiosyncrasies about your naming conventions
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
: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.
: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
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 / commitdiff