X-Git-Url: https://www.kengrimes.com/gitweb/?p=kengrimes.com%2Fcontent.git;a=blobdiff_plain;f=content.org;h=714e4f063bee59f3b96d75773a4a08949af13a38;hp=37aa9a4c117b067c55860be0d2f10854e9065260;hb=HEAD;hpb=c0683515ff9738eaabf6b9c93ea55d61deb33681 diff --git a/content.org b/content.org index 37aa9a4..714e4f0 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 @@ -638,19 +636,53 @@ This will make any ~:EXPORT_DESCRIPTION:~ properties export, instead, to a 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 @@ -668,8 +700,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,12 +723,18 @@ 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 -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]]