:END:
** DONE Using ox-hugo To Build Websites with Emacs :org:emacs:hugo:@tutorial:
-CLOSED: [2018-04-11 Wed 21:56]
+CLOSED: [2018-04-19 Thu 18:06]
:PROPERTIES:
:EXPORT_FILE_NAME: ox-hugo-tutorial
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Exporting to Hugo's Blackfriday Markdown from Orgmode"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/org.png
+:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :header /img/org.png
:END:
This article explains in detail the process of setting up a bare-bones website
using Hugo and Org mode. My goal in writing this is to provide readers with a
with ~M-x org-info~.
*** Making a New Blog
-Compared to a generic Org file, the only important "extra" data that ox-hugo
-needs to properly export data is a ~:PROPERTIES: ... :END:~ block with
-definitions used for Hugo's [[https://gohugo.io/content-management/front-matter/][front matter]] (used for associating a title, header,
-or other custom data with the page it generates). ~:PROPERTIES:~ blocks are
-common in Org for defining arbitrary metadata about sections, and can be used in
-many such ways. Providing an ~:EXPORT_FILE_NAME:~ definition signals to ox-hugo
-that this heading is available for export, and that it should be exported to a
-markdown file with the name provided. For example, the ~:PROPERTIES:~ block of
-the page you're currently reading looks like this:
+Compared to a generic Org file, the only necessary data that ox-hugo needs to
+properly export to Hugo is an ~:EXPORT_FILE_NAME:~ property in the
+~:PROPERTIES:~ block of an Org heading. ~:PROPERTIES:~ blocks are common in Org
+for defining arbitrary metadata about sections, and ox-hugo uses them to
+generate Hugo's [[https://gohugo.io/content-management/front-matter/][front matter]] (used for associating a title, header, or other
+custom data with the page it generates). Providing an ~:EXPORT_FILE_NAME:~
+definition signals to ox-hugo that a particular heading is available for export
+to Hugo. For example, the ~:PROPERTIES:~ block of the page you're currently
+reading looks like this:
#+begin_src org
:PROPERTIES:
-:EXPORT_FILE_NAME: ox-hugo
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Exporting to Hugo's Blackfriday Markdown from Orgmode"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/org.png
+:EXPORT_FILE_NAME: ox-hugo-tutorial
+:EXPORT_DESCRIPTION: Exporting to Hugo's Blackfriday Markdown from Orgmode
+:EXPORT_HUGO_IMAGES: /img/org.png
:END:
#+end_src
-The ~:caption~ and ~:header~ variables are optional definitions allowed by the
-Speedy theme of this website, but the filename is the only required property for
-ox-hugo. So, as a minimal example, here's what a new blog might look like in its
-entirety:
+The ~:EXPORT_HUGO_IMAGES:~ and ~:EXPORT_DESCRIPTION:~ variables are optional
+definitions allowed by the Speedy theme of this website, but the filename is the
+only required property for ox-hugo. Our goal here is to organize the structure
+of our website as a tree using Org headers. So, as a minimal example, here's
+what a new site might look like in its entirety:
#+begin_src org -n
#+hugo_base_dir: .
-,* Home
+,* My Blog
:PROPERTIES:
:EXPORT_HUGO_SECTION:
+:END:
+,** Home
+:PROPERTIES:
:EXPORT_FILE_NAME: _index
:END:
This is the home of my blog!
-,** I have herpes
+,** One Bad Night
:PROPERTIES:
-:EXPORT_FILE_NAME: herpes
+:EXPORT_FILE_NAME: bad-night
:END:
Someone gave me herpes! Oh no!
#+end_src
The Org file can be placed in any directory so long as ~HUGO_BASE_DIR~ correctly
identifies the Hugo project's root directory. This path definition is required
-for any valid ox-hugo file, and in the example above uses ~.~ as the base
-directory, which assumes that the file will be placed in the hugo project's base
-directory. If you saved this file as hugotest.org, exported it with Org's
-exporter ~C-c C-e~ and selected the Hugo output ~H~ and the All Subtrees To
-Files option ~A~, you'd wind up with the following files in your directory:
+for any valid ox-hugo file, and in the example above uses ~#+hugo_base_dir: .~
+to specify that the base directory will be the same path as this Org file. If
+you saved this file as hugotest.org, exported it with Org's exporter ~C-c C-e~
+and selected the Hugo output ~H~ and the All Subtrees To Files option ~A~, you'd
+wind up with the following files in your directory:
#+begin_src
.
├── content
-│ ├── _index.md
-│ └── herpes.md
+│ ├── bad-night.md
+│ └── _index.md
└── hugotest.org
#+end_src
Most sites will be more than a blog, though, and will want multiple sections. In
would be the following:
#+begin_src org -n
#+hugo_base_dir: .
-,* My Homepage
+,* Site Root
+,** Homepage
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_MENU: :menu "main"
:END:
This is the home of my blog!
-,* My Blog
+,** Blog Posts
:PROPERTIES:
:EXPORT_HUGO_SECTION: posts
:END:
-,** My Blog Homepage
+,*** My Blog Homepage
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_FILE_NAME: _index
:END:
Man, look at all my blog posts.
-,** I have herpes
+,*** One Bad Night
:PROPERTIES:
-:EXPORT_FILE_NAME: herpes
+:EXPORT_FILE_NAME: bad-night
:END:
Someone gave me herpes! Oh no!
#+end_src
-Which yields the following:
+Which yields the following files on export:
#+begin_src
.
├── content
│ ├── _index.md
│ └── posts
-│ ├── herpes.md
+│ ├── bad-night.md
│ └── _index.md
└── hugotest.org
#+end_src
-As you might expect, this structure adheres to the Hugo [[https://gohugo.io/content-management/organization/][content management]]
-scheme. Additionally, the index files have been marked with menu metadata, which
-allows Hugo themes to automatically generate navigation menus from the markdown
-files. Hereafter, making new blog posts is as simple as adding new sub-headings
-under the "My Blog" heading, and exporting. As you can see, this is suitable for
-defining the hierarchical structure of any general website, not just
-blogs. Org mode and Hugo just make creating new pages so simple and
-well-structured that providing content is all that's required for a new page,
-blog entry, or entirely new site section. If you can blog with ox-hugo, you can
-deftly deploy any manner of web content, or even develop entire websites as
-naturally as you make blog posts. Any tool that can turn blogging and web
-development into the same task is quite an achievement!
+As you might expect if you're already familiar with Hugo, this structure adheres
+to the Hugo [[https://gohugo.io/content-management/organization/][content management]] scheme. Additionally, the index files have been
+marked with menu metadata, which allows Hugo themes to automatically generate
+navigation menus from the markdown files. Hereafter, making new blog posts is as
+simple as adding new sub-headings under the "Blog Posts" heading, and
+exporting. As you can see, this is suitable for defining the hierarchical
+structure of any general website, not just blogs. Org mode and Hugo just make
+creating new pages so simple and well-structured that providing content is all
+that's required for a new page, blog entry, or entirely new site section. If you
+can blog with ox-hugo, you can deftly deploy any manner of web content, or even
+develop entire websites as naturally as you make blog posts. Any tool that can
+turn blogging and web development into the same task is quite an achievement!
Of course, themes to style this content are another can of worms entirely, but
-it is sufficient for now to mention that Hugo makes [[https://gohugo.io/themes/installing-and-using-themes/][using themes]] as easy as
-downloading one and specifying it in Hugo's config file.
-
-One question you may ask is why the blog's homepage is not defined in the *My
-Blog* heading. This is a fair question! Property blocks are inherited by
-sub-headings, and as of the current version of ox-hugo even ~:EXPORT_HUGO_MENU:~
-properties are inherited. This might be intended by the content creator, but
-most likely you don't want every single post you make to be in the main menu. So
-it makes sense to define all your pages, including the index, as a sub-heading
-of the section definition (which specifies which sub-directory content will
-output to).
+we'll get to that soon. It is sufficient for now to mention that Hugo makes
+[[https://gohugo.io/themes/installing-and-using-themes/][using themes]] as easy as downloading one and specifying it in Hugo's config file.
+
+**** Heading Management
+One question you may ask is why the blog's homepage is not defined in the *Blog
+Posts* heading. This is a fair question! Any heading with an
+~:EXPORT_FILE_NAME:~ property will export /all/ of that heading's content,
+/including subheadings/ beneath it. This allows Org headings to be used as part
+of the content of a post, where they will be exported as markdown heading
+levels, which translate to HTML heading elements ~<h1>~, ~<h2>~, ~<h3>~,
+etcetera.
+
+Furthermore, properties other than ~:EXPORT_FILE_NAME:~ are /inherited/ by
+sub-headings, including the ~:EXPORT_HUGO_MENU:~ properties. A
+~:EXPORT_HUGO_MENU:~ property at the section root would cause all exported files
+within that section to be added to the menu specified. This might be intended by
+the content creator, but most likely you don't want every single post you make
+to be in the main menu. So it makes sense to define all your pages, including
+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.
-#+begin_src org -n 24
-,* Fishsticks
+#+begin_src org -n 25
+,** Fishsticks
:PROPERTIES:
-:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_HUGO_SECTION: fishsticks
+: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
In this example, we've defined the main homepage of the section inside the
-tier-1 heading for Fishsticks. This is valid, and produces the expected file output:
+tier-1 heading for Fishsticks. This is technically valid, and produces the
+expected file output:
#+begin_src
.
├── content
│ │ └── van-de-camps.md
│ ├── _index.md
│ └── posts
-│ ├── herpes.md
+│ ├── bad-night.md
│ └── _index.md
└── hugotest.org
#+end_src
I think these gave me the herpes.
#+end_src
Uh oh! Not only did these fishsticks give us herpes, they are now part of the
-main menu. Tisk tisk. So if you use this workflow, be sure to put your index
-pages in subheadings so that the tier-1 heading can be used for "global"
-definitions that affect all of the pages.
+main menu. Worse, when the index page was exported, each of the subsequent posts
+became part of its content:
+#+begin_src markdown -n
+---
+title: "Fishsticks"
+author: ["Ken Grimes"]
+draft: false
+menu:
+ main:
+ weight: 1001
+ identifier: "fishsticks"
+---
+
+This section devoted to Orson Wells, R.I.P.
+
+
+## Van De Camps {#van-de-camps}
-Another question might be why the index pages are named *_index*. You can use
-*index* instead of *_index*, the only difference is whether Hugo treats the
-index page as a leaf, or a branch, when [[https://gohugo.io/content-management/page-bundles/][bundling resources]] for Hugo to query
-during site generation. This is a relatively new addition to Hugo as of version
-0.39, and isn't fully functional or integrated well into ox-hugo, so I simply
-don't use it at the moment. I define all indexes as *_index* to make them
-branches because, in future versions, packaging files within bundles like this
-will provide a more stable way for Hugo themes to reference page- and
-section-specific files that accompany the content. Currently, I store all such
-files in the static folder, which is copied verbatim to the output directory by
-Hugo when the site is built.
+If this is fish, I'll be a monkey's uncle.
+
+
+## Gortons {#gortons}
+
+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
+:PROPERTIES:
+:EXPORT_HUGO_SECTION: fishsticks
+:END:
+,*** 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
+:PROPERTIES:
+:EXPORT_FILE_NAME: van-de-camps
+:END:
+If this is fish, I'll be a monkey's uncle.
+,*** Gortons
+:PROPERTIES:
+:EXPORT_FILE_NAME: gortons
+:END:
+I think these gave me the herpes.
+#+end_src
*** Hugo Setup
At this point, setting up Hugo and publishing is simple. [[https://gohugo.io/getting-started/installing/][Installing]] Hugo is
when you export).
So you have three choices:
-1. run ~hugo new site /path/to/some-new-dir~ and move your Org file to it
+1. run ~hugo new site /path/to/some-new-dir~ and move your Org file to this new
+ directory
2. simply ~rm -Rf content/~ to remove the content directory ox-hugo created,
then run ~hugo new site --force .~
3. don't even bother with the ~hugo new site~ command, and make a *config.toml*
- file manually.
+ file manually (the only file really required for Hugo to run).
It's convenient to do this through the ~hugo~ command because it will create
Hugo-specific subdirectories like archetypes, layouts, themes, etcetera, in
│ │ └── van-de-camps.md
│ ├── _index.md
│ └── posts
-│ ├── herpes.md
+│ ├── bad-night.md
│ └── _index.md
├── data
├── hugotest.org
├── static
└── themes
#+end_src
+
+**** Theming
+The last thing to do here is to download or create a theme for Hugo. As
+mentioned before, installing a theme is very simple. This blog uses a custom
+theme named Speedy that I have been developing to help myself learn Hugo's
+internals, but for this example I'll be using Kaushal Modi's [[https://github.com/kaushalmodi/hugo-bare-min-theme][bare-min theme]]. The
+bare-min theme is the best starting place out there for making new themes, and
+outputs basic HTML pages without any need to mess with CSS or JS. It also
+provides easy debugging facilities and search features.
+
+So let's install it! You can download the theme from its github page and extract
+it to the themes folder, or much more easily use git to clone it to your themes
+directory. ~git clone https://github.com/kaushalmodi/hugo-bare-min-theme.git
+themes/bare-min~ Then open up your *config.toml* file, and add the theme.
+#+begin_src toml -n
+baseURL = "http://example.org/"
+languageCode = "en-us"
+title = "My New Hugo Site"
+# Adding a theme:
+theme = "bare-min"
+#+end_src
+Be sure that the theme's name matches the theme directory's name in the *themes/*
+directory of your project base directory. (e.g. *themes/bare-min* here). That's it
+for installing the theme.
+
Now, running the command ~hugo~ with no subcommands will invoke the Hugo
generator on the current directory, and output finalized content in the
*public/* directory.
│ │ └── van-de-camps.md
│ ├── _index.md
│ └── posts
-│ ├── herpes.md
+│ ├── bad-night.md
│ └── _index.md
├── data
├── hugotest.org
├── layouts
├── public
│ ├── categories
+│ │ ├── index.html
│ │ └── index.xml
+│ ├── css
+│ │ └── github_chroma.css
│ ├── fishsticks
-│ │ └── index.xml
+│ │ ├── gortons
+│ │ │ └── index.html
+│ │ ├── index.html
+│ │ ├── index.xml
+│ │ └── van-de-camps
+│ │ └── index.html
+│ ├── index.html
│ ├── index.xml
+│ ├── js
+│ │ └── search.js
+│ ├── page
+│ │ └── 1
+│ │ └── index.html
│ ├── posts
+│ │ ├── bad-night
+│ │ │ └── index.html
+│ │ ├── index.html
│ │ └── index.xml
│ ├── sitemap.xml
│ └── tags
+│ ├── index.html
│ └── index.xml
├── static
-└── themes
+└── themes ...
#+end_src
Hugo, by default, generates xml files that are suitable for RSS feeds. With a
-theme installed, Hugo will produce more suitable web content (usually
-HTML). You'll notice from this default output however that Hugo creates a
-sitemap, and two directories for [[https://gohugo.io/content-management/taxonomies/][taxonomies]] that let you "tag" and "categorize"
-content. The taxonomy index pages allow users to browse content by category or
-tag. These taxonomies correspond to Org mode tags, and ox-hugo will
-automatically associated tagged headings with the tags taxonomy, or the
-categories taxonomy if prefixed with an @ symbol. You are free to define your
-own taxonomies, and even disable the default "tags" and "categories" taxonomies,
-but since Org mode tags directly translate to the default Hugo taxonomies, it
-makes sense to just use the default taxonomies for now.
-
-*** Example Hugo Site
-As an example, let's add some tags and categories to our *hugotest.org* file:
+theme installed, Hugo will produce more suitable web content (usually HTML) to
+be served over HTTP. The bare-min theme outputs HTML, provides CSS for doing
+chroma-based syntax highlighting (in case you include code blocks), and inline
+styles for basic page formatting. Generated pages also have a lot of useful
+debugging information. You'll also notice that Hugo has generated folders for
+"categories" and "tags". These are default organization labels for your content
+called [[https://gohugo.io/content-management/taxonomies/][taxonomies]].
+
+**** Taxonomies
+The taxonomy index pages allow users to browse content by category or tag. These
+taxonomies correspond to Org mode tags, and ox-hugo will automatically
+associated tagged headings with the tags taxonomy, or the categories taxonomy if
+prefixed with an @ symbol. You are free to define your own taxonomies, and even
+disable the default "tags" and "categories" taxonomies, but since Org mode tags
+directly translate to the default Hugo taxonomies, it makes sense to just use
+the default taxonomies for now.
+
+As an example of taxonomies, I'll add some tags and categories to our
+*hugotest.org* file to create a complete blog structure with tags and categories:
#+begin_src org -n
#+hugo_base_dir: .
-,* My Homepage
+,* Site Root
+,** Homepage
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_MENU: :menu "main"
:END:
This is the home of my blog!
-,* My Blog
+,** Blog Posts
:PROPERTIES:
:EXPORT_HUGO_SECTION: posts
:END:
-,** My Blog Homepage
+,*** My Blog Homepage
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_FILE_NAME: _index
:END:
Man, look at all my blog posts.
-,** I have herpes :@inanity:herpes:fear:
+,*** One Bad Night :@updates:herpes:fear:
:PROPERTIES:
-:EXPORT_FILE_NAME: herpes
+:EXPORT_FILE_NAME: bad-night
:END:
Someone gave me herpes! Oh no!
-,* Fishsticks
+,** Fishsticks
:PROPERTIES:
-:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_HUGO_SECTION: fishsticks
+:END:
+,*** 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 :@inanity:
+,*** Van De Camps :@reviews:fear:
:PROPERTIES:
:EXPORT_FILE_NAME: van-de-camps
:END:
If this is fish, I'll be a monkey's uncle.
-,** Gortons :@inanity:herpes:
+,*** Gortons :@reviews:herpes:
:PROPERTIES:
:EXPORT_FILE_NAME: gortons
:END:
I think these gave me the herpes.
#+end_src
-Exporting *hugotest.org* with ~C-c C-e H A~ and generate with ~hugo~ will yield
+Exporting *hugotest.org* with ~C-c C-e H A~ and generating with ~hugo~ will yield
the same file structure as before, but this time we'll see that the categories
-and tags directories have sections for our newly added tags.
-#+begin_src
-.
-├── archetypes
-│ └── default.md
-├── config.toml
-├── content
-│ ├── fishsticks
-│ │ ├── gortons.md
-│ │ ├── _index.md
-│ │ └── van-de-camps.md
-│ └── posts
-│ └── herpes.md
-├── data
-├── hugotest.org
-├── layouts
-├── public
-│ ├── categories
-│ │ ├── inanity
-│ │ │ └── index.xml
-│ │ └── index.xml
-│ ├── fishsticks
-│ │ └── index.xml
-│ ├── index.xml
-│ ├── posts
-│ │ └── index.xml
-│ ├── sitemap.xml
-│ └── tags
-│ ├── fear
-│ │ └── index.xml
-│ ├── herpes
-│ │ └── index.xml
-│ └── index.xml
-├── static
-└── themes
-#+end_src
-The index pages of taxonomies provide a list of all available taxonomies of that
-type, with links to lists that show content associated with that taxonomy. For
-instance, public/tags/index.xml looks like this:
-#+begin_src xml -n
-<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
-<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
- <channel>
- <title>Tags on My New Hugo Site</title>
- <link>http://example.org/tags/</link>
- <description>Recent content in Tags on My New Hugo Site</description>
- <generator>Hugo -- gohugo.io</generator>
- <language>en-us</language>
-
- <atom:link href="http://example.org/tags/index.xml" rel="self" type="application/rss+xml" />
-
-
- <item>
- <title>Fear</title>
- <link>http://example.org/tags/fear/</link>
- <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
- <guid>http://example.org/tags/fear/</guid>
- <description></description>
- </item>
-
- <item>
- <title>Herpes</title>
- <link>http://example.org/tags/herpes/</link>
- <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
- <guid>http://example.org/tags/herpes/</guid>
- <description></description>
- </item>
-
- </channel>
-</rss>
-#+end_src
-And public/tags/fear/index.xml looks like this:
-#+begin_src xml -n
-<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
-<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
- <channel>
- <title>Fear on My New Hugo Site</title>
- <link>http://example.org/tags/fear/</link>
- <description>Recent content in Fear on My New Hugo Site</description>
- <generator>Hugo -- gohugo.io</generator>
- <language>en-us</language>
-
- <atom:link href="http://example.org/tags/fear/index.xml" rel="self" type="application/rss+xml" />
-
-
- <item>
- <title>I have herpes</title>
- <link>http://example.org/posts/herpes/</link>
- <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
- <guid>http://example.org/posts/herpes/</guid>
- <description>Someone gave me herpes! Oh no!</description>
- </item>
-
- <item>
- <title>Van De Camps</title>
- <link>http://example.org/fishsticks/van-de-camps/</link>
- <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
- <guid>http://example.org/fishsticks/van-de-camps/</guid>
- <description>If this is fish, I&rsquo;ll be a monkey&rsquo;s uncle.</description>
- </item>
-
- </channel>
-</rss>
-#+end_src
-This allows themes to easily build navigation pages for browsing or querying
-taxonomies. Files like these are often useful to output as JSON (done by the
-theme) to allow Javascript-driven dynamic search features, but a simpler scheme
-can output HTML pages to browse taxonomies just as you would posts in a section
-(i.e. Org mode heading).
-
-**** Theming
-The last thing to do here is to download or create a theme for Hugo. As
-mentioned before, installing a theme is very simple. This blog uses a custom
-theme named Speedy that I have been developing to help myself learn Hugo's
-internals, but for this example I'll be using Kaushal Modi's [[https://github.com/kaushalmodi/hugo-bare-min-theme][bare-min theme]]. The
-bare-min theme is the best starting place out there for making new themes, and
-outputs basic HTML pages without any need to mess with CSS or JS. It also
-provides easy debugging facilities and search features.
-
-We'll just install it and generate the site again. You can download the theme
-from its github page and extract it to the themes folder, or much more easily
-use git to clone it to your themes directory.
-~git clone https://github.com/kaushalmodi/hugo-bare-min-theme.git themes/bare-min~
-Then open up your *config.toml* file, and add the theme.
-#+begin_src toml -n
-baseURL = "http://example.org/"
-languageCode = "en-us"
-title = "My New Hugo Site"
-# Adding a theme:
-theme = "bare-min"
-#+end_src
-Be sure that the theme's name matches the theme directory's name in the themes/
-directory of your project base directory. (e.g. themes/bare-min here).
-
-That's it for installing the theme. Just run ~hugo~ again, and behold your output:
+and tags directories have sections for our newly added taxonomies.
#+begin_src
.
└── public
├── categories
- │ ├── inanity
- │ │ ├── index.html
- │ │ └── index.xml
- │ ├── index.html
- │ └── index.xml
- ├── css
- │ └── github_chroma.css
- ├── fishsticks
- │ ├── gortons
- │ │ └── index.html
│ ├── index.html
│ ├── index.xml
- │ └── van-de-camps
- │ └── index.html
- ├── index.html
- ├── index.xml
- ├── js
- │ └── search.js
- ├── page
- │ └── 1
- │ └── index.html
- ├── posts
- │ ├── herpes
- │ │ └── index.html
- │ ├── index.html
- │ └── index.xml
- ├── sitemap.xml
+ │ ├── reviews
+ │ │ ├── index.html
+ │ │ └── index.xml
+ │ └── updates
+ │ ├── index.html
+ │ └── index.xml
└── tags
├── fear
│ ├── index.html
├── index.html
└── index.xml
#+end_src
-The bare-min theme outputs HTML, provides CSS for doing chroma-based syntax
-highlighting (in case you include code blocks), and inline styles for basic
-page formatting. Generated pages also have a lot of useful debugging information.
+The index pages of taxonomies provide a list of all available taxonomies of that
+type, each with list pages that show all content associated with them. This
+allows themes to easily build navigation pages for browsing or querying
+taxonomies. Files like these are often useful to output as JSON (done by the
+theme) to allow Javascript-driven dynamic search features, but a simpler scheme
+can output HTML pages to browse taxonomies just as you would posts in a section
+(i.e. Org mode heading).
+**** Serving Content
You can now serve the *public/* directory over an HTTP server. Hugo is packaged
with an internal [[https://gohugo.io/commands/hugo_server/][HTTP server]] to help with testing, which is quite convenient
-because it can automatically refresh whenever content in its content directory
+because it can automatically refresh whenever content in its *content/* directory
is updated (so when you export from ox-hugo, you don't have to run ~hugo~
again). To use it, simply run ~hugo server~ and point your browser at
http://localhost:1313 (1313 is the default ~--port~ argument for ~hugo server~).
-Eventually you'll want to move on to other themes, or develop your own, but at
+*** Additional Information
+Eventually you'll want to move on to [[https://themes.gohugo.io/][other themes]], or [[https://gohugo.io/themes/creating/][develop your own]], but at
this point you've got a fully functional blog publishing workflow from start to
-finish.
+finish that you can view in-browser as you develop.
-*** Attaching Files, Capturing Information & Automation
+**** Attaching Files, Capturing Information & Automation
Once you have a basic site structured in your Org file, you're ready to start
throwing information in it. It is of course sufficient to open the Org file and
edit it, but most Org mode users prefer to automate /everything/, and being able
including elisp snippets for [[https://ox-hugo.scripter.co/doc/org-capture-setup/][capture setup]], [[https://ox-hugo.scripter.co/doc/images-in-content/][image linking]], and [[https://ox-hugo.scripter.co/doc/auto-export-on-saving/][automating
exports]] when you save your Org file (so no more need to ~C-c C-e H A~ every
time, just save the file as usual with ~C-x C-s~).
+
+**** Indexes and Page Resources
+You may be wondering why our index pages are exported as *_index* rather than
+*index*. Hugo uses a concept called [[https://gohugo.io/content-management/page-bundles/][Page Bundles]] to organize exported
+content. The gist of this is that a file named *index* is known as a "Leaf Node"
+and cannot have any children. A file named *_index* is considered a "Branch
+Node" and allows nesting other bundles beneath it. In other words, an Org
+heading with an exported file name of *index* will be treated as a single page
+with no subfolders. This is useful for single pages, but a section index
+(e.g. for a blog) with many subpages and other resources will more than likely
+want to allow nested bundles beneath it.
+
+You may export an Org heading as a Page Bundle by providing the Org property
+~:EXPORT_HUGO_BUNDLE:~ with an argument (string) that will become the name of
+the folder created. If you do this, you will need to set the
+~:EXPORT_FILE_NAME:~ property to either *index* for Leaf Nodes, or *_index* for
+Branch Nodes.
+
+The [[https://ox-hugo.scripter.co/doc/org-capture-setup/][capture setup]] provided by Kaushal Modi above provides methods to
+automatically create either a normal page, or a leaf node bundle when invoking
+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
+
+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.
+
+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.
+
+**** Renaming Tags and Other Properties
+If a theme you are using has any idiosyncrasies about your naming conventions
+(e.g. if you export your content to more than one site using more than one
+theme), ox-hugo provides a [[https://ox-hugo.scripter.co/doc/replace-front-matter-keys/][convenient way]] to automatically replace any key
+values on export. This can be done on a per-heading, or a per-file basis.
+
+To replace keys for the entire file, simply add a property to the top of your
+Org file. For example:
+#+begin_src org
+#+hugo_front_matter_key_replace: description>summary
+#+end_src
+This will make any ~:EXPORT_DESCRIPTION:~ properties export, instead, to a
+"summary" key in the front-matter of your output markdown file. It will also be
+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
+,#+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.
+
** 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: :caption "Exporting to Hugo's Blackfriday Markdown from Orgmode"
+:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :heading "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
exporter. As an Emacs user, this allows me to instantly capture interesting
information I come across and publish it within seconds. Now I have no excuses!
-** DONE Another topic
-CLOSED: [2018-04-01 Sun 18:29]
-:PROPERTIES:
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
-:EXPORT_FILE_NAME: another-topic-1
-:END:
-This is just another topic, don't worry about it.
-
-** DONE Another topic :@test:test:
-CLOSED: [2018-04-01 Sun 18:30]
-:PROPERTIES:
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
-:EXPORT_FILE_NAME: another-topic-2
-:END:
-This is just another topic, don't worry about it.
-
-** DONE Another topic :@test:test:
-CLOSED: [2018-04-01 Sun 18:30]
-:PROPERTIES:
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
-:EXPORT_FILE_NAME: another-topic-3
-:END:
-This is just another topic, don't worry about it.
-
-** DONE Another topic :@test:test:
-CLOSED: [2018-04-01 Sun 18:30]
-:PROPERTIES:
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
-:EXPORT_FILE_NAME: another-topic-4
-:END:
-This is just another topic, don't worry about it.
-** DONE Another topic :@test:test:
-CLOSED: [2018-04-01 Sun 18:30]
-:PROPERTIES:
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
-:EXPORT_FILE_NAME: another-topic-5
-:END:
-This is just another topic, don't worry about it.
-** DONE Another topic :@test:test:
-CLOSED: [2018-04-01 Sun 18:30]
-:PROPERTIES:
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
-:EXPORT_FILE_NAME: another-topic-6
-:END:
-This is just another topic, don't worry about it.
-** DONE Another topic :@test:test:
-CLOSED: [2018-04-01 Sun 18:30]
-:PROPERTIES:
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
-:EXPORT_FILE_NAME: another-topic-7
-:END:
-This is just another topic, don't worry about it.
-** DONE Another topic :@test:test:
-CLOSED: [2018-04-01 Sun 18:30]
-:PROPERTIES:
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
-:EXPORT_FILE_NAME: another-topic-8
-:END:
-This is just another topic, don't worry about it.
-** DONE Another topic :@test:test:
-CLOSED: [2018-04-01 Sun 18:30]
-:PROPERTIES:
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
-:EXPORT_FILE_NAME: another-topic-9
-:END:
-This is just another topic, don't worry about it.
-** DONE Another topic :@test:test:
-CLOSED: [2018-04-01 Sun 18:30]
-:PROPERTIES:
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
-:EXPORT_FILE_NAME: another-topic-10
-:END:
-This is just another topic, don't worry about it.
-** DONE Another topic :@test:test:
-CLOSED: [2018-04-01 Sun 18:30]
-:PROPERTIES:
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
-:EXPORT_FILE_NAME: another-topic-11
-:END:
-This is just another topic, don't worry about it.
-** DONE Another topic :@test:test:
-CLOSED: [2018-04-01 Sun 18:30]
-:PROPERTIES:
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
-:EXPORT_FILE_NAME: another-topic-12
-:END:
-This is just another topic, don't worry about it.
-** DONE Another topic :@test:test:
-CLOSED: [2018-04-01 Sun 18:30]
-:PROPERTIES:
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png
-:EXPORT_FILE_NAME: another-topic-13
-:END:
-This is just another topic, don't worry about it.
* Forth
:PROPERTIES:
:EXPORT_FILE_NAME: _index
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]]
-* COMMENT
-** Why Emacs/Org
-#+attr_html: :class center
-[[file:static/img/emacs-logo.png]]
-
-Org mode is sometimes seen as an esoteric tool for an already esoteric IDE
-(Emacs), but to me it is the natural evolution of decades of careful work to do
-things the right way. When a software developer, after much study and
-deliberation, finally comes to the realization that we are all fundamentally
-programming one enormous system, it suddenly becomes important to understand the
-fundamentals of computing and peel away the abstractions we live in like layers
-of an onion. At the core, computer scientists will find that Names and Naming
-are the universal "API" with which we all work. As such, being able to work with
-raw words is invaluable to any serious student of computing. This is why the
-much ignored medium of plain text is, somewhat paradoxically, the most powerful
-of all tools for us. Indeed, Names and Naming have a long history of association
-with power, and it seems most sciences that recognize this relationship are
-themselves deemed "esoteric".
-
-It's easy to get washed away in the torrent of new-age development tools that
-add layer after layer of abstraction and "boilerplate" automation. These days,
-it's trivial with tools like [[http://en.wikipedia.org/wiki/Webstorm][Webstorm]], [[http://en.wikipedia.org/wiki/Xcode][Xcode]], or [[http://en.wikipedia.org/wiki/Visual_Studio][Visual Studio]] to start
-producing working code in minutes, regardless of experience or knowledge. It is
-much harder, and in many environments impossible, to really understand what you
-are doing. Most new programming languages, freed from developing sophisticated
-compiler backends by new tools like [[http://en.wikipedia.org/wiki/llvm][llvm]], have instead focused on providing
-tooling for automatically formatting, linting, bootstrapping, and even building
-code to make this process even easier. These tools enforce an opinionated
-workflow that, although good, are generally not portable to other languages or
-toolchains. Tools like these are medicine for remedying the enormous time sink
-and productivity loss suffered during configuration and setup. But like many
-medicines, they can lead to addiction, and dependency on the vendor who provided
-it. Eventually, being constrained to a single environment will cause essential
-skills to atrophy, or never develop in the first place, making the victim a
-slave to both their vendor and the drug.
-
-I'm no tea-totaller, though. These tools are part of my regular workflow, and I
-advocate using them when it is appropriate. The primary goal in developing
-skills is to unapolagetically empower yourself by /any/ means necessary. It's a
-balancing act, in the end, whether the drugs are hurting or hindering. Just be
-conscious of the debilitating effects of what the buzz-slingers call "vendor
-lock-in" these days. Study the topic, read the documentation, and understand
-everything that is going to happen when you invoke any command. This applies to
-tooling as well as library functions and even language statements - even
-english. Admittedly, that's a steep mountain to climb for most people, and
-crippling when wading through spaghetti-code, but you'll come to understand that
-the most powerful words are the ones you /didn't have to say/ in the first
-place.
-
-Emacs and Org mode take these philosophies to heart in different, and incomplete
-ways. Org mode is a plain text formatting system, not so dissimilar to markdown,
-bbcode, or even twitter's automatic recognition of hashtags and @s. It's a
-formatting engine that recognizes certain plain-text patterns as having special
-meanings, geared eponymously towards organization of data. For instance,
-
-
-
-Emacs and Org mode take these philosophies to heart. Partly because Emacs has
-been around in some form since the early 70s, While I extend this philosophy to
-my coding style, it's also integral
-
-** Blackfriday Markdown: Syntax
-#+begin_export md
-<ul id="ProjectSubmenu">
- <li><a href="/projects/markdown/" title="Markdown Project Page">Main</a></li>
- <li><a href="/projects/markdown/basics" title="Markdown Basics">Basics</a></li>
- <li><a class="selected" title="Markdown Syntax Documentation">Syntax</a></li>
- <li><a href="/projects/markdown/license" title="Pricing and License Information">License</a></li>
- <li><a href="/projects/markdown/dingus" title="Online Markdown Web Form">Dingus</a></li>
-</ul>
-
-
- * [Overview](#overview)
- * [Philosophy](#philosophy)
- * [Inline HTML](#html)
- * [Automatic Escaping for Special Characters](#autoescape)
- * [Block Elements](#block)
- * [Paragraphs and Line Breaks](#p)
- * [Headers](#header)
- * [Blockquotes](#blockquote)
- * [Lists](#list)
- * [Code Blocks](#precode)
- * [Horizontal Rules](#hr)
- * [Span Elements](#span)
- * [Links](#link)
- * [Emphasis](#em)
- * [Code](#code)
- * [Images](#img)
- * [Miscellaneous](#misc)
- * [Backslash Escapes](#backslash)
- * [Automatic Links](#autolink)
-
-
-**Note:** This document is itself written using Markdown; you
-can [see the source for it by adding '.text' to the URL][src].
-
- [src]: https://raw.githubusercontent.com/russross/blackfriday/master/testdata/Markdown%20Documentation%20-%20Syntax.text
-
- * * *
-
-<h2 id="overview">Overview</h2>
-
-<h3 id="philosophy">Philosophy</h3>
-
-Markdown is intended to be as easy-to-read and easy-to-write as is feasible.
-
-Readability, however, is emphasized above all else. A Markdown-formatted
-document should be publishable as-is, as plain text, without looking
-like it's been marked up with tags or formatting instructions. While
-Markdown's syntax has been influenced by several existing text-to-HTML
-filters -- including [Setext] [1], [atx] [2], [Textile] [3], [reStructuredText] [4],
-[Grutatext] [5], and [EtText] [6] -- the single biggest source of
-inspiration for Markdown's syntax is the format of plain text email.
-
- [1]: http://docutils.sourceforge.net/mirror/setext.html
- [2]: http://www.aaronsw.com/2002/atx/
- [3]: http://textism.com/tools/textile/
- [4]: http://docutils.sourceforge.net/rst.html
- [5]: http://www.triptico.com/software/grutatxt.html
- [6]: http://ettext.taint.org/doc/
-
-To this end, Markdown's syntax is comprised entirely of punctuation
-characters, which punctuation characters have been carefully chosen so
-as to look like what they mean. E.g., asterisks around a word actually
-look like \*emphasis\*. Markdown lists look like, well, lists. Even
-blockquotes look like quoted passages of text, assuming you've ever
-used email.
-
-
-
-<h3 id="html">Inline HTML</h3>
-
-Markdown's syntax is intended for one purpose: to be used as a
-format for *writing* for the web.
-
-Markdown is not a replacement for HTML, or even close to it. Its
-syntax is very small, corresponding only to a very small subset of
-HTML tags. The idea is *not* to create a syntax that makes it easier
-to insert HTML tags. In my opinion, HTML tags are already easy to
-insert. The idea for Markdown is to make it easy to read, write, and
-edit prose. HTML is a *publishing* format; Markdown is a *writing*
-format. Thus, Markdown's formatting syntax only addresses issues that
-can be conveyed in plain text.
-
-For any markup that is not covered by Markdown's syntax, you simply
-use HTML itself. There's no need to preface it or delimit it to
-indicate that you're switching from Markdown to HTML; you just use
-the tags.
-
-The only restrictions are that block-level HTML elements -- e.g. `<div>`,
-`<table>`, `<pre>`, `<p>`, etc. -- must be separated from surrounding
-content by blank lines, and the start and end tags of the block should
-not be indented with tabs or spaces. Markdown is smart enough not
-to add extra (unwanted) `<p>` tags around HTML block-level tags.
-
-For example, to add an HTML table to a Markdown article:
-
- This is a regular paragraph.
-
- <table>
- <tr>
- <td>Foo</td>
- </tr>
- </table>
-
- This is another regular paragraph.
-
-Note that Markdown formatting syntax is not processed within block-level
-HTML tags. E.g., you can't use Markdown-style `*emphasis*` inside an
-HTML block.
-
-Span-level HTML tags -- e.g. `<span>`, `<cite>`, or `<del>` -- can be
-used anywhere in a Markdown paragraph, list item, or header. If you
-want, you can even use HTML tags instead of Markdown formatting; e.g. if
-you'd prefer to use HTML `<a>` or `<img>` tags instead of Markdown's
-link or image syntax, go right ahead.
-
-Unlike block-level HTML tags, Markdown syntax *is* processed within
-span-level tags.
-
-
-<h3 id="autoescape">Automatic Escaping for Special Characters</h3>
-
-In HTML, there are two characters that demand special treatment: `<`
-and `&`. Left angle brackets are used to start tags; ampersands are
-used to denote HTML entities. If you want to use them as literal
-characters, you must escape them as entities, e.g. `<`, and
-`&`.
-
-Ampersands in particular are bedeviling for web writers. If you want to
-write about 'AT&T', you need to write '`AT&T`'. You even need to
-escape ampersands within URLs. Thus, if you want to link to:
-
- http://images.google.com/images?num=30&q=larry+bird
-
-you need to encode the URL as:
-
- http://images.google.com/images?num=30&q=larry+bird
-
-in your anchor tag `href` attribute. Needless to say, this is easy to
-forget, and is probably the single most common source of HTML validation
-errors in otherwise well-marked-up web sites.
-
-Markdown allows you to use these characters naturally, taking care of
-all the necessary escaping for you. If you use an ampersand as part of
-an HTML entity, it remains unchanged; otherwise it will be translated
-into `&`.
-
-So, if you want to include a copyright symbol in your article, you can write:
-
- ©
-
-and Markdown will leave it alone. But if you write:
-
- AT&T
-
-Markdown will translate it to:
-
- AT&T
-
-Similarly, because Markdown supports [inline HTML](#html), if you use
-angle brackets as delimiters for HTML tags, Markdown will treat them as
-such. But if you write:
-
- 4 < 5
-
-Markdown will translate it to:
-
- 4 < 5
-
-However, inside Markdown code spans and blocks, angle brackets and
-ampersands are *always* encoded automatically. This makes it easy to use
-Markdown to write about HTML code. (As opposed to raw HTML, which is a
-terrible format for writing about HTML syntax, because every single `<`
-and `&` in your example code needs to be escaped.)
-
-
- * * *
-
-
-<h2 id="block">Block Elements</h2>
-
-
-<h3 id="p">Paragraphs and Line Breaks</h3>
-
-A paragraph is simply one or more consecutive lines of text, separated
-by one or more blank lines. (A blank line is any line that looks like a
-blank line -- a line containing nothing but spaces or tabs is considered
-blank.) Normal paragraphs should not be intended with spaces or tabs.
-
-The implication of the "one or more consecutive lines of text" rule is
-that Markdown supports "hard-wrapped" text paragraphs. This differs
-significantly from most other text-to-HTML formatters (including Movable
-Type's "Convert Line Breaks" option) which translate every line break
-character in a paragraph into a `<br />` tag.
-
-When you *do* want to insert a `<br />` break tag using Markdown, you
-end a line with two or more spaces, then type return.
-
-Yes, this takes a tad more effort to create a `<br />`, but a simplistic
-"every line break is a `<br />`" rule wouldn't work for Markdown.
-Markdown's email-style [blockquoting][bq] and multi-paragraph [list items][l]
-work best -- and look better -- when you format them with hard breaks.
-
- [bq]: #blockquote
- [l]: #list
-
-
-
-<h3 id="header">Headers</h3>
-
-Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
-
-Setext-style headers are "underlined" using equal signs (for first-level
-headers) and dashes (for second-level headers). For example:
-
- This is an H1
- =============
-
- This is an H2
- -------------
-
-Any number of underlining `=`'s or `-`'s will work.
-
-Atx-style headers use 1-6 hash characters at the start of the line,
-corresponding to header levels 1-6. For example:
-
- # This is an H1
-
- ## This is an H2
-
- ###### This is an H6
-
-Optionally, you may "close" atx-style headers. This is purely
-cosmetic -- you can use this if you think it looks better. The
-closing hashes don't even need to match the number of hashes
-used to open the header. (The number of opening hashes
-determines the header level.) :
-
- # This is an H1 #
-
- ## This is an H2 ##
-
- ### This is an H3 ######
-
-
-<h3 id="blockquote">Blockquotes</h3>
-
-Markdown uses email-style `>` characters for blockquoting. If you're
-familiar with quoting passages of text in an email message, then you
-know how to create a blockquote in Markdown. It looks best if you hard
-wrap the text and put a `>` before every line:
-
- > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
- > consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
- > Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
- >
- > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
- > id sem consectetuer libero luctus adipiscing.
-
-Markdown allows you to be lazy and only put the `>` before the first
-line of a hard-wrapped paragraph:
-
- > This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
- consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
- Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.
-
- > Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
- id sem consectetuer libero luctus adipiscing.
-
-Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
-adding additional levels of `>`:
-
- > This is the first level of quoting.
- >
- > > This is nested blockquote.
- >
- > Back to the first level.
-
-Blockquotes can contain other Markdown elements, including headers, lists,
-and code blocks:
-
- > ## This is a header.
- >
- > 1. This is the first list item.
- > 2. This is the second list item.
- >
- > Here's some example code:
- >
- > return shell_exec("echo $input | $markdown_script");
-
-Any decent text editor should make email-style quoting easy. For
-example, with BBEdit, you can make a selection and choose Increase
-Quote Level from the Text menu.
-
-
-<h3 id="list">Lists</h3>
-
-Markdown supports ordered (numbered) and unordered (bulleted) lists.
-
-Unordered lists use asterisks, pluses, and hyphens -- interchangably
--- as list markers:
-
- * Red
- * Green
- * Blue
-
-is equivalent to:
-
- + Red
- + Green
- + Blue
-
-and:
-
- - Red
- - Green
- - Blue
-
-Ordered lists use numbers followed by periods:
-
- 1. Bird
- 2. McHale
- 3. Parish
-
-It's important to note that the actual numbers you use to mark the
-list have no effect on the HTML output Markdown produces. The HTML
-Markdown produces from the above list is:
-
- <ol>
- <li>Bird</li>
- <li>McHale</li>
- <li>Parish</li>
- </ol>
-
-If you instead wrote the list in Markdown like this:
-
- 1. Bird
- 1. McHale
- 1. Parish
-
-or even:
-
- 3. Bird
- 1. McHale
- 8. Parish
-
-you'd get the exact same HTML output. The point is, if you want to,
-you can use ordinal numbers in your ordered Markdown lists, so that
-the numbers in your source match the numbers in your published HTML.
-But if you want to be lazy, you don't have to.
-
-If you do use lazy list numbering, however, you should still start the
-list with the number 1. At some point in the future, Markdown may support
-starting ordered lists at an arbitrary number.
-
-List markers typically start at the left margin, but may be indented by
-up to three spaces. List markers must be followed by one or more spaces
-or a tab.
-
-To make lists look nice, you can wrap items with hanging indents:
-
- * Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
- Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
- viverra nec, fringilla in, laoreet vitae, risus.
- * Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
- Suspendisse id sem consectetuer libero luctus adipiscing.
-
-But if you want to be lazy, you don't have to:
-
- * Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
- Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
- viverra nec, fringilla in, laoreet vitae, risus.
- * Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
- Suspendisse id sem consectetuer libero luctus adipiscing.
-
-If list items are separated by blank lines, Markdown will wrap the
-items in `<p>` tags in the HTML output. For example, this input:
-
- * Bird
- * Magic
-
-will turn into:
-
- <ul>
- <li>Bird</li>
- <li>Magic</li>
- </ul>
-
-But this:
-
- * Bird
-
- * Magic
-
-will turn into:
-
- <ul>
- <li><p>Bird</p></li>
- <li><p>Magic</p></li>
- </ul>
-
-List items may consist of multiple paragraphs. Each subsequent
-paragraph in a list item must be intended by either 4 spaces
-or one tab:
-
- 1. This is a list item with two paragraphs. Lorem ipsum dolor
- sit amet, consectetuer adipiscing elit. Aliquam hendrerit
- mi posuere lectus.
-
- Vestibulum enim wisi, viverra nec, fringilla in, laoreet
- vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
- sit amet velit.
-
- 2. Suspendisse id sem consectetuer libero luctus adipiscing.
-
-It looks nice if you indent every line of the subsequent
-paragraphs, but here again, Markdown will allow you to be
-lazy:
-
- * This is a list item with two paragraphs.
-
- This is the second paragraph in the list item. You're
- only required to indent the first line. Lorem ipsum dolor
- sit amet, consectetuer adipiscing elit.
-
- * Another item in the same list.
-
-To put a blockquote within a list item, the blockquote's `>`
-delimiters need to be indented:
-
- * A list item with a blockquote:
-
- > This is a blockquote
- > inside a list item.
-
-To put a code block within a list item, the code block needs
-to be indented *twice* -- 8 spaces or two tabs:
-
- * A list item with a code block:
-
- <code goes here>
-
-
-It's worth noting that it's possible to trigger an ordered list by
-accident, by writing something like this:
-
- 1986. What a great season.
-
-In other words, a *number-period-space* sequence at the beginning of a
-line. To avoid this, you can backslash-escape the period:
-
- 1986\. What a great season.
-
-
-
-<h3 id="precode">Code Blocks</h3>
-
-Pre-formatted code blocks are used for writing about programming or
-markup source code. Rather than forming normal paragraphs, the lines
-of a code block are interpreted literally. Markdown wraps a code block
-in both `<pre>` and `<code>` tags.
-
-To produce a code block in Markdown, simply indent every line of the
-block by at least 4 spaces or 1 tab. For example, given this input:
-
- This is a normal paragraph:
-
- This is a code block.
-
-Markdown will generate:
-
- <p>This is a normal paragraph:</p>
-
- <pre><code>This is a code block.
- </code></pre>
-
-One level of indentation -- 4 spaces or 1 tab -- is removed from each
-line of the code block. For example, this:
-
- Here is an example of AppleScript:
-
- tell application "Foo"
- beep
- end tell
-
-will turn into:
-
- <p>Here is an example of AppleScript:</p>
-
- <pre><code>tell application "Foo"
- beep
- end tell
- </code></pre>
-
-A code block continues until it reaches a line that is not indented
-(or the end of the article).
-
-Within a code block, ampersands (`&`) and angle brackets (`<` and `>`)
-are automatically converted into HTML entities. This makes it very
-easy to include example HTML source code using Markdown -- just paste
-it and indent it, and Markdown will handle the hassle of encoding the
-ampersands and angle brackets. For example, this:
-
- <div class="footer">
- © 2004 Foo Corporation
- </div>
-
-will turn into:
-
- <pre><code><div class="footer">
- &copy; 2004 Foo Corporation
- </div>
- </code></pre>
-
-Regular Markdown syntax is not processed within code blocks. E.g.,
-asterisks are just literal asterisks within a code block. This means
-it's also easy to use Markdown to write about Markdown's own syntax.
-
-
-
-<h3 id="hr">Horizontal Rules</h3>
-
-You can produce a horizontal rule tag (`<hr />`) by placing three or
-more hyphens, asterisks, or underscores on a line by themselves. If you
-wish, you may use spaces between the hyphens or asterisks. Each of the
-following lines will produce a horizontal rule:
-
- * * *
-
- ***
-
- *****
-
- - - -
-
- ---------------------------------------
-
- _ _ _
-
-
- * * *
-
-<h2 id="span">Span Elements</h2>
-
-<h3 id="link">Links</h3>
-
-Markdown supports two style of links: *inline* and *reference*.
-
-In both styles, the link text is delimited by [square brackets].
-
-To create an inline link, use a set of regular parentheses immediately
-after the link text's closing square bracket. Inside the parentheses,
-put the URL where you want the link to point, along with an *optional*
-title for the link, surrounded in quotes. For example:
-
- This is [an example](http://example.com/ "Title") inline link.
-
- [This link](http://example.net/) has no title attribute.
-
-Will produce:
-
- <p>This is <a href="http://example.com/" title="Title">
- an example</a> inline link.</p>
-
- <p><a href="http://example.net/">This link</a> has no
- title attribute.</p>
-
-If you're referring to a local resource on the same server, you can
-use relative paths:
-
- See my [About](/about/) page for details.
-
-Reference-style links use a second set of square brackets, inside
-which you place a label of your choosing to identify the link:
-
- This is [an example][id] reference-style link.
-
-You can optionally use a space to separate the sets of brackets:
-
- This is [an example] [id] reference-style link.
-
-Then, anywhere in the document, you define your link label like this,
-on a line by itself:
-
- [id]: http://example.com/ "Optional Title Here"
-
-That is:
-
- * Square brackets containing the link identifier (optionally
- indented from the left margin using up to three spaces);
- * followed by a colon;
- * followed by one or more spaces (or tabs);
- * followed by the URL for the link;
- * optionally followed by a title attribute for the link, enclosed
- in double or single quotes.
-
-The link URL may, optionally, be surrounded by angle brackets:
-
- [id]: <http://example.com/> "Optional Title Here"
-
-You can put the title attribute on the next line and use extra spaces
-or tabs for padding, which tends to look better with longer URLs:
-
- [id]: http://example.com/longish/path/to/resource/here
- "Optional Title Here"
-
-Link definitions are only used for creating links during Markdown
-processing, and are stripped from your document in the HTML output.
-
-Link definition names may constist of letters, numbers, spaces, and punctuation -- but they are *not* case sensitive. E.g. these two links:
-
- [link text][a]
- [link text][A]
-
-are equivalent.
-
-The *implicit link name* shortcut allows you to omit the name of the
-link, in which case the link text itself is used as the name.
-Just use an empty set of square brackets -- e.g., to link the word
-"Google" to the google.com web site, you could simply write:
-
- [Google][]
-
-And then define the link:
-
- [Google]: http://google.com/
-
-Because link names may contain spaces, this shortcut even works for
-multiple words in the link text:
-
- Visit [Daring Fireball][] for more information.
-
-And then define the link:
-
- [Daring Fireball]: http://daringfireball.net/
-
-Link definitions can be placed anywhere in your Markdown document. I
-tend to put them immediately after each paragraph in which they're
-used, but if you want, you can put them all at the end of your
-document, sort of like footnotes.
-
-Here's an example of reference links in action:
-
- I get 10 times more traffic from [Google] [1] than from
- [Yahoo] [2] or [MSN] [3].
-
- [1]: http://google.com/ "Google"
- [2]: http://search.yahoo.com/ "Yahoo Search"
- [3]: http://search.msn.com/ "MSN Search"
-
-Using the implicit link name shortcut, you could instead write:
-
- I get 10 times more traffic from [Google][] than from
- [Yahoo][] or [MSN][].
-
- [google]: http://google.com/ "Google"
- [yahoo]: http://search.yahoo.com/ "Yahoo Search"
- [msn]: http://search.msn.com/ "MSN Search"
-
-Both of the above examples will produce the following HTML output:
-
- <p>I get 10 times more traffic from <a href="http://google.com/"
- title="Google">Google</a> than from
- <a href="http://search.yahoo.com/" title="Yahoo Search">Yahoo</a>
- or <a href="http://search.msn.com/" title="MSN Search">MSN</a>.</p>
-
-For comparison, here is the same paragraph written using
-Markdown's inline link style:
-
- I get 10 times more traffic from [Google](http://google.com/ "Google")
- than from [Yahoo](http://search.yahoo.com/ "Yahoo Search") or
- [MSN](http://search.msn.com/ "MSN Search").
-
-The point of reference-style links is not that they're easier to
-write. The point is that with reference-style links, your document
-source is vastly more readable. Compare the above examples: using
-reference-style links, the paragraph itself is only 81 characters
-long; with inline-style links, it's 176 characters; and as raw HTML,
-it's 234 characters. In the raw HTML, there's more markup than there
-is text.
-
-With Markdown's reference-style links, a source document much more
-closely resembles the final output, as rendered in a browser. By
-allowing you to move the markup-related metadata out of the paragraph,
-you can add links without interrupting the narrative flow of your
-prose.
-
-
-<h3 id="em">Emphasis</h3>
-
-Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
-emphasis. Text wrapped with one `*` or `_` will be wrapped with an
-HTML `<em>` tag; double `*`'s or `_`'s will be wrapped with an HTML
-`<strong>` tag. E.g., this input:
-
- *single asterisks*
-
- _single underscores_
-
- **double asterisks**
-
- __double underscores__
-
-will produce:
-
- <em>single asterisks</em>
-
- <em>single underscores</em>
-
- <strong>double asterisks</strong>
-
- <strong>double underscores</strong>
-
-You can use whichever style you prefer; the lone restriction is that
-the same character must be used to open and close an emphasis span.
-
-Emphasis can be used in the middle of a word:
-
- un*fucking*believable
-
-But if you surround an `*` or `_` with spaces, it'll be treated as a
-literal asterisk or underscore.
-
-To produce a literal asterisk or underscore at a position where it
-would otherwise be used as an emphasis delimiter, you can backslash
-escape it:
-
- \*this text is surrounded by literal asterisks\*
-
-
-
-<h3 id="code">Code</h3>
-
-To indicate a span of code, wrap it with backtick quotes (`` ` ``).
-Unlike a pre-formatted code block, a code span indicates code within a
-normal paragraph. For example:
-
- Use the `printf()` function.
-
-will produce:
-
- <p>Use the <code>printf()</code> function.</p>
-
-To include a literal backtick character within a code span, you can use
-multiple backticks as the opening and closing delimiters:
-
- ``There is a literal backtick (`) here.``
-
-which will produce this:
-
- <p><code>There is a literal backtick (`) here.</code></p>
-
-The backtick delimiters surrounding a code span may include spaces --
-one after the opening, one before the closing. This allows you to place
-literal backtick characters at the beginning or end of a code span:
-
- A single backtick in a code span: `` ` ``
-
- A backtick-delimited string in a code span: `` `foo` ``
-
-will produce:
-
- <p>A single backtick in a code span: <code>`</code></p>
-
- <p>A backtick-delimited string in a code span: <code>`foo`</code></p>
-
-With a code span, ampersands and angle brackets are encoded as HTML
-entities automatically, which makes it easy to include example HTML
-tags. Markdown will turn this:
-
- Please don't use any `<blink>` tags.
-
-into:
-
- <p>Please don't use any <code><blink></code> tags.</p>
-
-You can write this:
-
- `—` is the decimal-encoded equivalent of `—`.
-
-to produce:
-
- <p><code>&#8212;</code> is the decimal-encoded
- equivalent of <code>&mdash;</code>.</p>
-
-
-
-<h3 id="img">Images</h3>
-
-Admittedly, it's fairly difficult to devise a "natural" syntax for
-placing images into a plain text document format.
-
-Markdown uses an image syntax that is intended to resemble the syntax
-for links, allowing for two styles: *inline* and *reference*.
-
-Inline image syntax looks like this:
-
- 
-
- 
-
-That is:
-
- * An exclamation mark: `!`;
- * followed by a set of square brackets, containing the `alt`
- attribute text for the image;
- * followed by a set of parentheses, containing the URL or path to
- the image, and an optional `title` attribute enclosed in double
- or single quotes.
-
-Reference-style image syntax looks like this:
-
- ![Alt text][id]
-
-Where "id" is the name of a defined image reference. Image references
-are defined using syntax identical to link references:
-
- [id]: url/to/image "Optional title attribute"
-
-As of this writing, Markdown has no syntax for specifying the
-dimensions of an image; if this is important to you, you can simply
-use regular HTML `<img>` tags.
-
-
- * * *
-
-
-<h2 id="misc">Miscellaneous</h2>
-
-<h3 id="autolink">Automatic Links</h3>
-
-Markdown supports a shortcut style for creating "automatic" links for URLs and email addresses: simply surround the URL or email address with angle brackets. What this means is that if you want to show the actual text of a URL or email address, and also have it be a clickable link, you can do this:
-
- <http://example.com/>
-
-Markdown will turn this into:
-
- <a href="http://example.com/">http://example.com/</a>
-
-Automatic links for email addresses work similarly, except that
-Markdown will also perform a bit of randomized decimal and hex
-entity-encoding to help obscure your address from address-harvesting
-spambots. For example, Markdown will turn this:
-
- <address@example.com>
-
-into something like this:
-
- <a href="mailto:addre
- ss@example.co
- m">address@exa
- mple.com</a>
-
-which will render in a browser as a clickable link to "address@example.com".
-
-(This sort of entity-encoding trick will indeed fool many, if not
-most, address-harvesting bots, but it definitely won't fool all of
-them. It's better than nothing, but an address published in this way
-will probably eventually start receiving spam.)
-
-
-
-<h3 id="backslash">Backslash Escapes</h3>
-
-Markdown allows you to use backslash escapes to generate literal
-characters which would otherwise have special meaning in Markdown's
-formatting syntax. For example, if you wanted to surround a word with
-literal asterisks (instead of an HTML `<em>` tag), you can backslashes
-before the asterisks, like this:
-
- \*literal asterisks\*
-
-Markdown provides backslash escapes for the following characters:
-
- \ backslash
- ` backtick
- * asterisk
- _ underscore
- {} curly braces
- [] square brackets
- () parentheses
- # hash mark
- + plus sign
- - minus sign (hyphen)
- . dot
- ! exclamation mark
-#+end_export
-** OS Wars
-The operating system wars are still going, they've just taken on a new form: the
-ecosystems of major software development centers like microsoft, facebook,
-google, apple, amazon, have just become the new battleground. All of these
-ecosystems are seeking to replace the entire unix operating system stack with
-their own internal APIs and code. from writing code in awk/sed/bash to utilize
-the OS's commands as an api, to generalizing this in python-esque languages, and
-now to new programming frameworks for every language which package endless
-libraries that are just sloppy new rewrites of decades-old functionality already
-in the GNU environment. the good news is that there's a ton of energy going into
-language research, compilers, and there are many new emerging standards as a
-result for message sending (alan kay "real objects"), network federation,
-package management, build tools, live coding, web technology, execution
-platforms, and everything in between. the bad news is that basically all energy
-is just going towards building, and rebuilding, and rebuilding application
-frameworks. Call them libraries, packages, eggs, utilities, or whatever, they're
-all just another incomplete rewrite of tools that have been around and
-maintained for over half a century. They're easier to use, which is great, but
-that user interface (i.e. language syntax and package management) doesn't need
-to be divorced from existing functionality. As far as I can figure, it's just
-gouche, or somehow seen as less sophisticated and interesting, if a language
-keeps C dependencies after a certain point. Almost all languages start out their
-life as C programs, and it's considered a major milestone when the language's
-compiler can finally compile itself and become self-hosting. All this proves is
-that the language can generate a compiler, though. It's a sloppy metric of
-progress. It's another major milestone when the language's libraries no longer
-have any C library dependencies (i.e. all commonly used APIs for handling i18n,
-unicode, hashtables, etcetera, have been reinvented in the new
-language). And perhaps its greatest achievement of all is to remove dependence
-on libc - the single most rugged and well-tested system interface on the
-planet.
-
-What I'd really like to see is a language that
---
title: "Using ox-hugo To Build Websites with Emacs"
author: ["Ken Grimes"]
-date: 2018-04-11T21:56:00-07:00
+date: 2018-04-19T18:06:00-07:00
tags: ["org", "emacs", "hugo"]
categories: ["tutorial"]
draft: false
-caption: "Exporting to Hugo's Blackfriday Markdown from Orgmode"
header: "/img/org.png"
---
This article explains in detail the process of setting up a bare-bones website
-using Hugo and org-mode. My goal in writing this is to provide readers with a
+using Hugo and Org mode. My goal in writing this is to provide readers with a
superior understanding of the fundamentals of this workflow. It is by no means
-an exhaustive explanation of org-mode or Emacs, but should give readers of any
+an exhaustive explanation of Org mode or Emacs, but should give readers of any
skill level a strong foundation to apply their own knowledge and techniques to
the Emacs-Hugo toolchain.
# Intro & Setup {#intro-and-setup}
-[Kaushal Modi](https://github.com/kaushalmodi) made ox-hugo by extending org's ox-blackfriday package, providing
-an impressive amount of features for organizing blog text and linked data with
+[Kaushal Modi](https://github.com/kaushalmodi) created ox-hugo on top of his ox-blackfriday package, providing an
+impressive amount of features for organizing blog text and linked data with
Hugo. He maintains [great documentation](https://ox-hugo.scripter.co/) and ample [examples](https://github.com/kaushalmodi/ox-hugo/tree/master/test/site/content-org) for using the
package. I will explain my own workflow here, but for an exhaustive (though
-terse) reference, I highly recommend Modi's [test site](https://ox-hugo.scripter.co/test/) and [post source](https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/all-posts.org) org file,
+terse) reference, I highly recommend Modi's [test site](https://ox-hugo.scripter.co/test/) and [post source](https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/all-posts.org) Org file,
which contain demonstrations and tests for all of ox-hugo's features.
After issuing the Emacs command `M-x package-install RET ox-hugo RET`, you'll
need to `require` it. You can do this by running `M-: (require 'ox-hugo)`, but
you'll want to add it to your configuration as explained [here](https://ox-hugo.scripter.co/doc/usage/). Once this is
-done, using ox-hugo is just a matter of making an org file and writing
+done, using ox-hugo is just a matter of making an Org file and writing
content. Org's format is very straightforward, and is designed to make sense to
the reader even if they're unfamiliar with the formal syntax. For instance,
| Brussel Sprouts | 32 | 4 | 0 | :=vsum($2..$4) |
```
-Produces a dynamic spreadsheet table in org-mode that exports to HTML like this:
+Produces a dynamic spreadsheet table in Org mode that exports to HTML like this:
## My food {#my-food}
| Marshmallows | 0 | 100 | 20 | 120 |
| Brussel Sprouts | 32 | 4 | 0 | 36 |
-If you're already familiar with org-mode, the benefits are obvious and creating
-content is fairly trivial. Org-mode is, however, a complex and expansive program
+If you're already familiar with Org mode, the benefits are obvious and creating
+content is fairly trivial. Org mode is, however, a complex and expansive program
with many features, and its learning curve can appear daunting at first glance.
Using ox-hugo is a great way to learn the format, since it gives the author a
command-center view of their entire content hierarchy, much like a traditional
database, but in a flat format that's much easier to read and understand. Org
features present themselves naturally, and the author can easily visualize the
-correspondence between the org format and the output on their webpage.
+correspondence between the Org format and the output on their webpage.
-Just take a look at the [org file](https://www.kengrimes.com/gitweb/?p=kengrimes.com/content.git;a=blob_plain;f=content.org;hb=HEAD) for this webpage. Search for "ox-hugo is super
+Just take a look at the [Org file](https://www.kengrimes.com/gitweb/?p=kengrimes.com/content.git;a=blob_plain;f=content.org;hb=HEAD) for this webpage. Search for "ox-hugo is super
cool!" and you should find this very paragraph.
Eventually you'll want to [read the manual](https://orgmode.org/manual/), though. You may access it in Emacs
# Making a New Blog {#making-a-new-blog}
-Compared to a generic org file, the only important "extra" data that ox-hugo
-needs to properly export data is a `:PROPERTIES: ... :END:` block with
-definitions used for Hugo's [front matter](https://gohugo.io/content-management/front-matter/) (used for associating a title, header,
-or other custom data with the page it generates). `:PROPERTIES:` blocks are
-common in org for defining arbitrary metadata about sections, and can be used in
-many such ways. Providing an `:EXPORT_FILE_NAME:` definition signals to ox-hugo
-that this heading is available for export, and that it should be exported to a
-markdown file with the name provided. For example, the `:PROPERTIES:` block of
-the page you're currently reading looks like this:
+Compared to a generic Org file, the only necessary data that ox-hugo needs to
+properly export to Hugo is an `:EXPORT_FILE_NAME:` property in the
+`:PROPERTIES:` block of an Org heading. `:PROPERTIES:` blocks are common in Org
+for defining arbitrary metadata about sections, and ox-hugo uses them to
+generate Hugo's [front matter](https://gohugo.io/content-management/front-matter/) (used for associating a title, header, or other
+custom data with the page it generates). Providing an `:EXPORT_FILE_NAME:`
+definition signals to ox-hugo that a particular heading is available for export
+to Hugo. For example, the `:PROPERTIES:` block of the page you're currently
+reading looks like this:
```org
:PROPERTIES:
-:EXPORT_FILE_NAME: ox-hugo
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "Exporting to Hugo's Blackfriday Markdown from Orgmode"
-:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/org.png
+:EXPORT_FILE_NAME: ox-hugo-tutorial
+:EXPORT_DESCRIPTION: Exporting to Hugo's Blackfriday Markdown from Orgmode
+:EXPORT_HUGO_IMAGES: /img/org.png
:END:
```
-The `:caption` and `:header` variables are optional definitions allowed by the
-Speedy theme of this website, but the filename is the only required property for
-ox-hugo. So, as a minimal example, here's what a new blog might look like in its
-entirety:
+The `:EXPORT_HUGO_IMAGES:` and `:EXPORT_DESCRIPTION:` variables are optional
+definitions allowed by the Speedy theme of this website, but the filename is the
+only required property for ox-hugo. Our goal here is to organize the structure
+of our website as a tree using Org headers. So, as a minimal example, here's
+what a new site might look like in its entirety:
{{< highlight org "linenos=table, linenostart=1" >}}
#+hugo_base_dir: .
-* Home
+* My Blog
:PROPERTIES:
:EXPORT_HUGO_SECTION:
+:END:
+** Home
+:PROPERTIES:
:EXPORT_FILE_NAME: _index
:END:
This is the home of my blog!
-** I have herpes
+** One Bad Night
:PROPERTIES:
-:EXPORT_FILE_NAME: herpes
+:EXPORT_FILE_NAME: bad-night
:END:
Someone gave me herpes! Oh no!
{{< /highlight >}}
-The org file can be placed in any directory so long as `HUGO_BASE_DIR` correctly
+The Org file can be placed in any directory so long as `HUGO_BASE_DIR` correctly
identifies the Hugo project's root directory. This path definition is required
-for any valid ox-hugo file, and in the example above uses `.` as the base
-directory, which assumes that the file will be placed in the hugo project's base
-directory. If you saved this file as hugotest.org, exported it with org's
-exporter `C-c C-e` and selected the Hugo output `H` and the All Subtrees To
-Files option `A`, you'd wind up with the following files in your directory:
+for any valid ox-hugo file, and in the example above uses `#+hugo_base_dir: .`
+to specify that the base directory will be the same path as this Org file. If
+you saved this file as hugotest.org, exported it with Org's exporter `C-c C-e`
+and selected the Hugo output `H` and the All Subtrees To Files option `A`, you'd
+wind up with the following files in your directory:
```nil
.
├── content
-│ ├── _index.md
-│ └── herpes.md
+│ ├── bad-night.md
+│ └── _index.md
└── hugotest.org
```
{{< highlight org "linenos=table, linenostart=1" >}}
#+hugo_base_dir: .
-* My Homepage
+* Site Root
+** Homepage
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_MENU: :menu "main"
:END:
This is the home of my blog!
-* My Blog
+** Blog Posts
:PROPERTIES:
:EXPORT_HUGO_SECTION: posts
:END:
-** My Blog Homepage
+*** My Blog Homepage
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_FILE_NAME: _index
:END:
Man, look at all my blog posts.
-** I have herpes
+*** One Bad Night
:PROPERTIES:
-:EXPORT_FILE_NAME: herpes
+:EXPORT_FILE_NAME: bad-night
:END:
Someone gave me herpes! Oh no!
{{< /highlight >}}
-Which yields the following:
+Which yields the following files on export:
```nil
.
├── content
│ ├── _index.md
│ └── posts
-│ ├── herpes.md
+│ ├── bad-night.md
│ └── _index.md
└── hugotest.org
```
-As you might expect, this structure adheres to the Hugo [content management](https://gohugo.io/content-management/organization/)
-scheme. Additionally, the index files have been marked with menu metadata, which
-allows Hugo themes to automatically generate navigation menus from the markdown
-files. Hereafter, making new blog posts is as simple as adding new sub-headings
-under the "My Blog" heading, and exporting. As you can see, this is suitable for
-defining the hierarchical structure of any general website, not just
-blogs. Org-mode and Hugo just make creating new pages so simple and
-well-structured that providing content is all that's required for a new page,
-blog entry, or entirely new site section. If you can blog with ox-hugo, you can
-deftly deploy any manner of web content, or even develop entire websites as
-naturally as you make blog posts. Any tool that can turn blogging and web
-development into the same task is quite an achievement!
+As you might expect if you're already familiar with Hugo, this structure adheres
+to the Hugo [content management](https://gohugo.io/content-management/organization/) scheme. Additionally, the index files have been
+marked with menu metadata, which allows Hugo themes to automatically generate
+navigation menus from the markdown files. Hereafter, making new blog posts is as
+simple as adding new sub-headings under the "Blog Posts" heading, and
+exporting. As you can see, this is suitable for defining the hierarchical
+structure of any general website, not just blogs. Org mode and Hugo just make
+creating new pages so simple and well-structured that providing content is all
+that's required for a new page, blog entry, or entirely new site section. If you
+can blog with ox-hugo, you can deftly deploy any manner of web content, or even
+develop entire websites as naturally as you make blog posts. Any tool that can
+turn blogging and web development into the same task is quite an achievement!
Of course, themes to style this content are another can of worms entirely, but
-it is sufficient for now to mention that Hugo makes [using themes](https://gohugo.io/themes/installing-and-using-themes/) as easy as
-downloading one and specifying it in Hugo's config file.
-
-One question you may ask is why the blog's homepage is not defined in the **My
-Blog** heading. This is a fair question! Property blocks are inherited by
-sub-headings, and as of the current version of ox-hugo even `:EXPORT_HUGO_MENU:`
-properties are inherited. This might be intended by the content creator, but
-most likely you don't want every single post you make to be in the main menu. So
-it makes sense to define all your pages, including the index, as a sub-heading
-of the section definition (which specifies which sub-directory content will
-output to).
+we'll get to that soon. It is sufficient for now to mention that Hugo makes
+[using themes](https://gohugo.io/themes/installing-and-using-themes/) as easy as downloading one and specifying it in Hugo's config file.
+
+
+## Heading Management {#heading-management}
+
+One question you may ask is why the blog's homepage is not defined in the **Blog
+Posts** heading. This is a fair question! Any heading with an
+`:EXPORT_FILE_NAME:` property will export _all_ of that heading's content,
+_including subheadings_ beneath it. This allows Org headings to be used as part
+of the content of a post, where they will be exported as markdown heading
+levels, which translate to HTML heading elements `<h1>`, `<h2>`, `<h3>`,
+etcetera.
+
+Furthermore, properties other than `:EXPORT_FILE_NAME:` are _inherited_ by
+sub-headings, including the `:EXPORT_HUGO_MENU:` properties. A
+`:EXPORT_HUGO_MENU:` property at the section root would cause all exported files
+within that section to be added to the menu specified. This might be intended by
+the content creator, but most likely you don't want every single post you make
+to be in the main menu. So it makes sense to define all your pages, including
+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.
-{{< highlight org "linenos=table, linenostart=24" >}}
-* Fishsticks
+{{< highlight org "linenos=table, linenostart=25" >}}
+** Fishsticks
:PROPERTIES:
-:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_HUGO_SECTION: fishsticks
+: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:
{{< /highlight >}}
In this example, we've defined the main homepage of the section inside the
-tier-1 heading for Fishsticks. This is valid, and produces the expected file output:
+tier-1 heading for Fishsticks. This is technically valid, and produces the
+expected file output:
```nil
.
│ │ └── van-de-camps.md
│ ├── _index.md
│ └── posts
-│ ├── herpes.md
+│ ├── bad-night.md
│ └── _index.md
└── hugotest.org
```
{{< /highlight >}}
Uh oh! Not only did these fishsticks give us herpes, they are now part of the
-main menu. Tisk tisk. So if you use this workflow, be sure to put your index
-pages in subheadings so that the tier-1 heading can be used for "global"
-definitions that affect all of the pages.
-
-Another question might be why the index pages are named **\_index**. You can use
-**index** instead of **\_index**, the only difference is whether Hugo treats the
-index page as a leaf, or a branch, when [bundling resources](https://gohugo.io/content-management/page-bundles/) for Hugo to query
-during site generation. This is a relatively new addition to Hugo as of version
-0.39, and isn't fully functional or integrated well into ox-hugo, so I simply
-don't use it at the moment. I define all indexes as **\_index** to make them
-branches because, in future versions, packaging files within bundles like this
-will provide a more stable way for Hugo themes to reference page- and
-section-specific files that accompany the content. Currently, I store all such
-files in the static folder, which is copied verbatim to the output directory by
-Hugo when the site is built.
+main menu. Worse, when the index page was exported, each of the subsequent posts
+became part of its content:
+
+{{< highlight markdown "linenos=table, linenostart=1" >}}
+---
+title: "Fishsticks"
+author: ["Ken Grimes"]
+draft: false
+menu:
+ main:
+ weight: 1001
+ identifier: "fishsticks"
+---
+
+This section devoted to Orson Wells, R.I.P.
+
+
+## Van De Camps {#van-de-camps}
+
+If this is fish, I'll be a monkey's uncle.
+
+
+## Gortons {#gortons}
+
+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:
+
+{{< highlight org "linenos=table, linenostart=25" >}}
+** Fishsticks
+:PROPERTIES:
+:EXPORT_HUGO_SECTION: fishsticks
+:END:
+*** 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
+:PROPERTIES:
+:EXPORT_FILE_NAME: van-de-camps
+:END:
+If this is fish, I'll be a monkey's uncle.
+*** Gortons
+:PROPERTIES:
+:EXPORT_FILE_NAME: gortons
+:END:
+I think these gave me the herpes.
+{{< /highlight >}}
# Hugo Setup {#hugo-setup}
So you have three choices:
-1. run `hugo new site /path/to/some-new-dir` and move your org file to it
+1. run `hugo new site /path/to/some-new-dir` and move your Org file to this new
+ directory
2. simply `rm -Rf content/` to remove the content directory ox-hugo created,
then run `hugo new site --force .`
3. don't even bother with the `hugo new site` command, and make a **config.toml**
- file manually.
+ file manually (the only file really required for Hugo to run).
It's convenient to do this through the `hugo` command because it will create
Hugo-specific subdirectories like archetypes, layouts, themes, etcetera, in
│ │ └── van-de-camps.md
│ ├── _index.md
│ └── posts
-│ ├── herpes.md
+│ ├── bad-night.md
│ └── _index.md
├── data
├── hugotest.org
└── themes
```
+
+## Theming {#theming}
+
+The last thing to do here is to download or create a theme for Hugo. As
+mentioned before, installing a theme is very simple. This blog uses a custom
+theme named Speedy that I have been developing to help myself learn Hugo's
+internals, but for this example I'll be using Kaushal Modi's [bare-min theme](https://github.com/kaushalmodi/hugo-bare-min-theme). The
+bare-min theme is the best starting place out there for making new themes, and
+outputs basic HTML pages without any need to mess with CSS or JS. It also
+provides easy debugging facilities and search features.
+
+So let's install it! You can download the theme from its github page and extract
+it to the themes folder, or much more easily use git to clone it to your themes
+directory. `git clone https://github.com/kaushalmodi/hugo-bare-min-theme.git
+themes/bare-min` Then open up your **config.toml** file, and add the theme.
+
+{{< highlight toml "linenos=table, linenostart=1" >}}
+baseURL = "http://example.org/"
+languageCode = "en-us"
+title = "My New Hugo Site"
+# Adding a theme:
+theme = "bare-min"
+{{< /highlight >}}
+
+Be sure that the theme's name matches the theme directory's name in the **themes/**
+directory of your project base directory. (e.g. **themes/bare-min** here). That's it
+for installing the theme.
+
Now, running the command `hugo` with no subcommands will invoke the Hugo
generator on the current directory, and output finalized content in the
**public/** directory.
│ │ └── van-de-camps.md
│ ├── _index.md
│ └── posts
-│ ├── herpes.md
+│ ├── bad-night.md
│ └── _index.md
├── data
├── hugotest.org
├── layouts
├── public
│ ├── categories
+│ │ ├── index.html
│ │ └── index.xml
+│ ├── css
+│ │ └── github_chroma.css
│ ├── fishsticks
-│ │ └── index.xml
+│ │ ├── gortons
+│ │ │ └── index.html
+│ │ ├── index.html
+│ │ ├── index.xml
+│ │ └── van-de-camps
+│ │ └── index.html
+│ ├── index.html
│ ├── index.xml
+│ ├── js
+│ │ └── search.js
+│ ├── page
+│ │ └── 1
+│ │ └── index.html
│ ├── posts
+│ │ ├── bad-night
+│ │ │ └── index.html
+│ │ ├── index.html
│ │ └── index.xml
│ ├── sitemap.xml
│ └── tags
+│ ├── index.html
│ └── index.xml
├── static
-└── themes
+└── themes ...
```
Hugo, by default, generates xml files that are suitable for RSS feeds. With a
-theme installed, Hugo will produce more suitable web content (usually
-HTML). You'll notice from this default output however that Hugo creates a
-sitemap, and two directories for [taxonomies](https://gohugo.io/content-management/taxonomies/) that let you "tag" and "categorize"
-content. The taxonomy index pages allow users to browse content by category or
-tag. These taxonomies correspond to org-mode tags, and ox-hugo will
-automatically associated tagged headings with the tags taxonomy, or the
-categories taxonomy if prefixed with an @ symbol. You are free to define your
-own taxonomies, and even disable the default "tags" and "categories" taxonomies,
-but since org-mode tags directly translate to the default Hugo taxonomies, it
-makes sense to just use the default taxonomies for now.
+theme installed, Hugo will produce more suitable web content (usually HTML) to
+be served over HTTP. The bare-min theme outputs HTML, provides CSS for doing
+chroma-based syntax highlighting (in case you include code blocks), and inline
+styles for basic page formatting. Generated pages also have a lot of useful
+debugging information. You'll also notice that Hugo has generated folders for
+"categories" and "tags". These are default organization labels for your content
+called [taxonomies](https://gohugo.io/content-management/taxonomies/).
+
+## Taxonomies {#taxonomies}
-# Example Hugo Site {#example-hugo-site}
+The taxonomy index pages allow users to browse content by category or tag. These
+taxonomies correspond to Org mode tags, and ox-hugo will automatically
+associated tagged headings with the tags taxonomy, or the categories taxonomy if
+prefixed with an @ symbol. You are free to define your own taxonomies, and even
+disable the default "tags" and "categories" taxonomies, but since Org mode tags
+directly translate to the default Hugo taxonomies, it makes sense to just use
+the default taxonomies for now.
-As an example, let's add some tags and categories to our **hugotest.org** file:
+As an example of taxonomies, I'll add some tags and categories to our
+**hugotest.org** file to create a complete blog structure with tags and categories:
{{< highlight org "linenos=table, linenostart=1" >}}
#+hugo_base_dir: .
-* My Homepage
+* Site Root
+** Homepage
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_MENU: :menu "main"
:END:
This is the home of my blog!
-* My Blog
+** Blog Posts
:PROPERTIES:
:EXPORT_HUGO_SECTION: posts
:END:
-** My Blog Homepage
+*** My Blog Homepage
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_FILE_NAME: _index
:END:
Man, look at all my blog posts.
-** I have herpes :@inanity:herpes:fear:
+*** One Bad Night :@updates:herpes:fear:
:PROPERTIES:
-:EXPORT_FILE_NAME: herpes
+:EXPORT_FILE_NAME: bad-night
:END:
Someone gave me herpes! Oh no!
-* Fishsticks
+** Fishsticks
:PROPERTIES:
-:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_HUGO_SECTION: fishsticks
+:END:
+*** 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 :@inanity:
+*** Van De Camps :@reviews:fear:
:PROPERTIES:
:EXPORT_FILE_NAME: van-de-camps
:END:
If this is fish, I'll be a monkey's uncle.
-** Gortons :@inanity:herpes:
+*** Gortons :@reviews:herpes:
:PROPERTIES:
:EXPORT_FILE_NAME: gortons
:END:
I think these gave me the herpes.
{{< /highlight >}}
-Exporting **hugotest.org** with `C-c C-e H A` and generate with `hugo` will yield
+Exporting **hugotest.org** with `C-c C-e H A` and generating with `hugo` will yield
the same file structure as before, but this time we'll see that the categories
-and tags directories have sections for our newly added tags.
-
-```nil
-.
-├── archetypes
-│ └── default.md
-├── config.toml
-├── content
-│ ├── fishsticks
-│ │ ├── gortons.md
-│ │ ├── _index.md
-│ │ └── van-de-camps.md
-│ └── posts
-│ └── herpes.md
-├── data
-├── hugotest.org
-├── layouts
-├── public
-│ ├── categories
-│ │ ├── inanity
-│ │ │ └── index.xml
-│ │ └── index.xml
-│ ├── fishsticks
-│ │ └── index.xml
-│ ├── index.xml
-│ ├── posts
-│ │ └── index.xml
-│ ├── sitemap.xml
-│ └── tags
-│ ├── fear
-│ │ └── index.xml
-│ ├── herpes
-│ │ └── index.xml
-│ └── index.xml
-├── static
-└── themes
-```
-
-The index pages of taxonomies provide a list of all available taxonomies of that
-type, with links to lists that show content associated with that taxonomy. For
-instance, public/tags/index.xml looks like this:
-
-{{< highlight xml "linenos=table, linenostart=1" >}}
-<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
-<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
- <channel>
- <title>Tags on My New Hugo Site</title>
- <link>http://example.org/tags/</link>
- <description>Recent content in Tags on My New Hugo Site</description>
- <generator>Hugo -- gohugo.io</generator>
- <language>en-us</language>
-
- <atom:link href="http://example.org/tags/index.xml" rel="self" type="application/rss+xml" />
-
-
- <item>
- <title>Fear</title>
- <link>http://example.org/tags/fear/</link>
- <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
- <guid>http://example.org/tags/fear/</guid>
- <description></description>
- </item>
-
- <item>
- <title>Herpes</title>
- <link>http://example.org/tags/herpes/</link>
- <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
- <guid>http://example.org/tags/herpes/</guid>
- <description></description>
- </item>
-
- </channel>
-</rss>
-{{< /highlight >}}
-
-And public/tags/fear/index.xml looks like this:
-
-{{< highlight xml "linenos=table, linenostart=1" >}}
-<?xml version="1.0" encoding="utf-8" standalone="yes" ?>
-<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
- <channel>
- <title>Fear on My New Hugo Site</title>
- <link>http://example.org/tags/fear/</link>
- <description>Recent content in Fear on My New Hugo Site</description>
- <generator>Hugo -- gohugo.io</generator>
- <language>en-us</language>
-
- <atom:link href="http://example.org/tags/fear/index.xml" rel="self" type="application/rss+xml" />
-
-
- <item>
- <title>I have herpes</title>
- <link>http://example.org/posts/herpes/</link>
- <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
- <guid>http://example.org/posts/herpes/</guid>
- <description>Someone gave me herpes! Oh no!</description>
- </item>
-
- <item>
- <title>Van De Camps</title>
- <link>http://example.org/fishsticks/van-de-camps/</link>
- <pubDate>Mon, 01 Jan 0001 00:00:00 +0000</pubDate>
-
- <guid>http://example.org/fishsticks/van-de-camps/</guid>
- <description>If this is fish, I&rsquo;ll be a monkey&rsquo;s uncle.</description>
- </item>
-
- </channel>
-</rss>
-{{< /highlight >}}
-
-This allows themes to easily build navigation pages for browsing or querying
-taxonomies. Files like these are often useful to output as JSON (done by the
-theme) to allow Javascript-driven dynamic search features, but a simpler scheme
-can output HTML pages to browse taxonomies just as you would posts in a section
-(i.e. org-mode heading).
-
-
-## Theming {#theming}
-
-The last thing to do here is to download or create a theme for Hugo. As
-mentioned before, installing a theme is very simple. This blog uses a custom
-theme named Speedy that I have been developing to help myself learn Hugo's
-internals, but for this example I'll be using Kaushal Modi's [bare-min theme](https://github.com/kaushalmodi/hugo-bare-min-theme). The
-bare-min theme is the best starting place out there for making new themes, and
-outputs basic HTML pages without any need to mess with CSS or JS. It also
-provides easy debugging facilities and search features.
-
-We'll just install it and generate the site again. You can download the theme
-from its github page and extract it to the themes folder, or much more easily
-use git to clone it to your themes directory.
-`git clone https://github.com/kaushalmodi/hugo-bare-min-theme.git themes/bare-min`
-Then open up your **config.toml** file, and add the theme.
-
-{{< highlight toml "linenos=table, linenostart=1" >}}
-baseURL = "http://example.org/"
-languageCode = "en-us"
-title = "My New Hugo Site"
-# Adding a theme:
-theme = "bare-min"
-{{< /highlight >}}
-
-Be sure that the theme's name matches the theme directory's name in the themes/
-directory of your project base directory. (e.g. themes/bare-min here).
-
-That's it for installing the theme. Just run `hugo` again, and behold your output:
+and tags directories have sections for our newly added taxonomies.
```nil
.
└── public
├── categories
- │ ├── inanity
- │ │ ├── index.html
- │ │ └── index.xml
- │ ├── index.html
- │ └── index.xml
- ├── css
- │ └── github_chroma.css
- ├── fishsticks
- │ ├── gortons
- │ │ └── index.html
│ ├── index.html
│ ├── index.xml
- │ └── van-de-camps
- │ └── index.html
- ├── index.html
- ├── index.xml
- ├── js
- │ └── search.js
- ├── page
- │ └── 1
- │ └── index.html
- ├── posts
- │ ├── herpes
- │ │ └── index.html
- │ ├── index.html
- │ └── index.xml
- ├── sitemap.xml
+ │ ├── reviews
+ │ │ ├── index.html
+ │ │ └── index.xml
+ │ └── updates
+ │ ├── index.html
+ │ └── index.xml
└── tags
├── fear
│ ├── index.html
└── index.xml
```
-The bare-min theme outputs HTML, provides CSS for doing chroma-based syntax
-highlighting (in case you include code blocks), and inline styles for basic
-page formatting. Generated pages also have a lot of useful debugging information.
+The index pages of taxonomies provide a list of all available taxonomies of that
+type, each with list pages that show all content associated with them. This
+allows themes to easily build navigation pages for browsing or querying
+taxonomies. Files like these are often useful to output as JSON (done by the
+theme) to allow Javascript-driven dynamic search features, but a simpler scheme
+can output HTML pages to browse taxonomies just as you would posts in a section
+(i.e. Org mode heading).
+
+
+## Serving Content {#serving-content}
You can now serve the **public/** directory over an HTTP server. Hugo is packaged
with an internal [HTTP server](https://gohugo.io/commands/hugo_server/) to help with testing, which is quite convenient
-because it can automatically refresh whenever content in its content directory
+because it can automatically refresh whenever content in its **content/** directory
is updated (so when you export from ox-hugo, you don't have to run `hugo`
again). To use it, simply run `hugo server` and point your browser at
<http://localhost:1313> (1313 is the default `--port` argument for `hugo server`).
-Eventually you'll want to move on to other themes, or develop your own, but at
+
+# Additional Information {#additional-information}
+
+Eventually you'll want to move on to [other themes](https://themes.gohugo.io/), or [develop your own](https://gohugo.io/themes/creating/), but at
this point you've got a fully functional blog publishing workflow from start to
-finish.
+finish that you can view in-browser as you develop.
-# Attaching Files, Capturing Information & Automation {#attaching-files-capturing-information-and-automation}
+## Attaching Files, Capturing Information & Automation {#attaching-files-capturing-information-and-automation}
-Once you have a basic site structured in your org file, you're ready to start
-throwing information in it. It is of course sufficient to open the org file and
-edit it, but most org-mode users prefer to automate _everything_, and being able
-to use org's capture feature to instantly populate new blog posts is extremely
+Once you have a basic site structured in your Org file, you're ready to start
+throwing information in it. It is of course sufficient to open the Org file and
+edit it, but most Org mode users prefer to automate _everything_, and being able
+to use Org's capture feature to instantly populate new blog posts is extremely
convenient.
The [ox-hugo documentation](https://ox-hugo.scripter.co/) provides succinct explanations on how to do this,
including elisp snippets for [capture setup](https://ox-hugo.scripter.co/doc/org-capture-setup/), [image linking](https://ox-hugo.scripter.co/doc/images-in-content/), and [automating
-exports](https://ox-hugo.scripter.co/doc/auto-export-on-saving/) when you save your org file (so no more need to `C-c C-e H A` every
+exports](https://ox-hugo.scripter.co/doc/auto-export-on-saving/) when you save your Org file (so no more need to `C-c C-e H A` every
time, just save the file as usual with `C-x C-s`).
+
+
+## Indexes and Page Resources {#indexes-and-page-resources}
+
+You may be wondering why our index pages are exported as **\_index** rather than
+**index**. Hugo uses a concept called [Page Bundles](https://gohugo.io/content-management/page-bundles/) to organize exported
+content. The gist of this is that a file named **index** is known as a "Leaf Node"
+and cannot have any children. A file named **\_index** is considered a "Branch
+Node" and allows nesting other bundles beneath it. In other words, an Org
+heading with an exported file name of **index** will be treated as a single page
+with no subfolders. This is useful for single pages, but a section index
+(e.g. for a blog) with many subpages and other resources will more than likely
+want to allow nested bundles beneath it.
+
+You may export an Org heading as a Page Bundle by providing the Org property
+`:EXPORT_HUGO_BUNDLE:` with an argument (string) that will become the name of
+the folder created. If you do this, you will need to set the
+`:EXPORT_FILE_NAME:` property to either **index** for Leaf Nodes, or **\_index** for
+Branch Nodes.
+
+The [capture setup](https://ox-hugo.scripter.co/doc/org-capture-setup/) provided by Kaushal Modi above provides methods to
+automatically create either a normal page, or a leaf node bundle when invoking
+Org Capture.
+
+
+## Drafts and Automatic Timestamps {#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:
+
+```markdown
+---
+title: "{{ replace .Name "-" " " | title }}"
+date: {{ .Date }}
+draft: true
+---
+```
+
+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.
+
+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.
+
+
+## Renaming Tags and Other Properties {#renaming-tags-and-other-properties}
+
+If a theme you are using has any idiosyncrasies about your naming conventions
+(e.g. if you export your content to more than one site using more than one
+theme), ox-hugo provides a [convenient way](https://ox-hugo.scripter.co/doc/replace-front-matter-keys/) to automatically replace any key
+values on export. This can be done on a per-heading, or a per-file basis.
+
+To replace keys for the entire file, simply add a property to the top of your
+Org file. For example:
+
+```org
+#+hugo_front_matter_key_replace: description>summary
+```
+
+This will make any `:EXPORT_DESCRIPTION:` properties export, instead, to a
+"summary" key in the front-matter of your output markdown file. It will also be
+able to replace exported values in the Org body:
+
+```org
+#+begin_description
+This is the description, but will export as the Summary value in front-matter
+#+end_description
+```
+
+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.
projects / kengrimes.com / content.git / commitdiff