: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
+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.
I assume only beginner-level knowledge of Emacs.
*** Intro & Setup
-[[https://github.com/kaushalmodi][Kaushal Modi]] made ox-hugo by extending org's ox-blackfriday package, providing
-an impressive amount of features for organizing blog text and linked data with
+[[https://github.com/kaushalmodi][Kaushal Modi]] 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 [[https://ox-hugo.scripter.co/][great documentation]] and ample [[https://github.com/kaushalmodi/ox-hugo/tree/master/test/site/content-org][examples]] for using the
package. I will explain my own workflow here, but for an exhaustive (though
-terse) reference, I highly recommend Modi's [[https://ox-hugo.scripter.co/test/][test site]] and [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/all-posts.org][post source]] org file,
+terse) reference, I highly recommend Modi's [[https://ox-hugo.scripter.co/test/][test site]] and [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/all-posts.org][post source]] 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 [[https://ox-hugo.scripter.co/doc/usage/][here]]. 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,
#+begin_src org
| Marshmallows | 0 | 100 | 20 | :=vsum($2..$4) |
| Brussel Sprouts | 32 | 4 | 0 | :=vsum($2..$4) |
#+end_src
-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
| Where's My Food? | Fridge | Counter | Mouth | Total |
| Oranges | 1 | 3 | 0 | 4 |
| Brussel Sprouts | 32 | 4 | 0 | 36 |
#+TBLFM: @2$5=vsum($2..$4)::@3$5=vsum($2..$4)::@4$5=vsum($2..$4)
-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 [[https://www.kengrimes.com/gitweb/?p=kengrimes.com/content.git;a=blob_plain;f=content.org;hb=HEAD][org file]] for this webpage. Search for "ox-hugo is super
+Just take a look at the [[https://www.kengrimes.com/gitweb/?p=kengrimes.com/content.git;a=blob_plain;f=content.org;hb=HEAD][Org file]] for this webpage. Search for "ox-hugo is super
cool!" and you should find this very paragraph.
Eventually you'll want to [[https://orgmode.org/manual/][read the manual]], though. You may access it in Emacs
with ~M-x org-info~.
*** Making a New Blog
-Compared to a generic org file, the only important "extra" data that ox-hugo
+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
+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
: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
+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
+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:
#+begin_src
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
+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
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 it
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*
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
+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
+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
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).
+(i.e. Org mode heading).
**** Theming
The last thing to do here is to download or create a theme for Hugo. As
finish.
*** 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
-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 [[https://ox-hugo.scripter.co/][ox-hugo documentation]] provides succinct explanations on how to do this,
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
+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~).
** DONE I did a blog :blog:org:emacs:hugo:
CLOSED: [2018-04-06 Fri 18:29]
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption "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
+ox-hugo is an [[http://en.wikipedia.org/wiki/Emacs][Emacs]] package for [[http://en.wikipedia.org/wiki/org-mode][Org mode]] that produces input for the static
content generator [[https://gohugo.io/][Hugo]], which I use for this website. Today I integrated its
expectations about file structure into the Speedy theme for this blog, allowing
-me to keep all blog contents in a single org-mode file and export [[http://en.wikipedia.org/wiki/markdown][markdown]]
+me to keep all blog contents in a single Org mode file and export [[http://en.wikipedia.org/wiki/markdown][markdown]]
content for Hugo's excellent [[https://github.com/russross/blackfriday][blackfriday markdown parser]] (a markdown format with
many added features). Hugo does support limited parsing of org files internally,
-but org-mode features like inline spreadsheets and system communication are
-beyond the scope of most external tools, so org-mode is best used as an
+but Org mode features like inline spreadsheets and system communication are
+beyond the scope of most external tools, so Org mode is best used as an
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!
#+attr_html: :class center
[[file:static/img/emacs-logo.png]]
-Org-mode is sometimes seen as an esoteric tool for an already esoteric IDE
+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
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,
+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
+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
projects / kengrimes.com / content.git / commitdiff