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
able to replace exported values in the Org body:
#+begin_src org
,#+begin_description
-This is the description, but will export as the Summary value in front-matter
+This is the description,
+it has multiple lines too!
+It will export as the Summary value in front-matter
,#+end_description
#+end_src
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.
+**** Why not use Hugo's internal Org parser?
+It's true that Hugo has an internal Org parser that is well maintained. It
+provides this as an alternative to markdown files. You may wonder, then, why
+someone would use Org mode to export to markdown instead of just letting Hugo
+parse the Org files itself. The answer is two-fold:
+1. Hugo's Org format is currently less feature complete than markdown, so
+ exporting from Org mode to the Hugo Org Format would limit potential output.
+2. Org mode is a lot more than just a file format, and its integration with your
+ system allows all kinds of benefits you can never get out of a simple Org
+ file parser.
+Therefore, supporting the Org format in another tool will give you a superior
+text format for organizing information, but it will be crippled when compared to
+an actual Org mode implementation. Ox-hugo gives you the ability to use Org mode
+itself to generate content.
+
+If Hugo's Org parser gains parity with, or eclipses, the Blackfriday Markdown
+format currently used by Hugo, ox-hugo could certainly be used to output those
+Org-Hugo files instead of the current markdown. This would be nice because it
+would allow Org mode users to view their output content more easily, but the
+advantages of ox-hugo and a real, bona fide Org mode would still remain.
+
+So you see, Hugo's Org parser isn't really in competition with ox-hugo, it's in
+competition with the /other/ Hugo parsers (e.g. markdown).
+
+*** 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
-complete. In the mean time, if you're curious, this is my [[file:static/cv.pdf][curriculum vitae]]
+complete. In the meantime, if you're curious, this is my [[file:static/cv.pdf][curriculum vitae]]
projects / kengrimes.com / content.git / blobdiff