#+hugo_base_dir: .
#+hugo_level_offset: 0
#+seq_todo: TODO DRAFT DONE
#+startup: indent showall
* Home
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:END:
** Computers are the Devil
:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :header /img/blog.png
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_MENU: :menu "main" :weight -1 :title Blog
:END:
** DONE Using ox-hugo To Build Websites with Emacs :org:emacs:hugo:@tutorial:
CLOSED: [2018-04-11 Wed 21:56]
: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
: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
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
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
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,
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
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
,* My food
| Where's My Food? | Fridge | Counter | Mouth | Total |
| Oranges | 1 | 3 | 0 | :=vsum($2..$4) |
| 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:
**** My food
| Where's My Food? | Fridge | Counter | Mouth | Total |
| Oranges | 1 | 3 | 0 | 4 |
| Marshmallows | 0 | 100 | 20 | 120 |
| 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
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.
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
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:
#+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
: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:
#+begin_src org -n
#+hugo_base_dir: .
,* Home
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:EXPORT_FILE_NAME: _index
:END:
This is the home of my blog!
,** I have herpes
:PROPERTIES:
:EXPORT_FILE_NAME: herpes
: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:
#+begin_src
.
├── content
│ ├── _index.md
│ └── herpes.md
└── hugotest.org
#+end_src
Most sites will be more than a blog, though, and will want multiple sections. In
fact, many sites are made up of nothing but a slew of sections that users
navigate between with some built-in menu. So a more functional minimal example
would be the following:
#+begin_src org -n
#+hugo_base_dir: .
,* My Homepage
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_MENU: :menu "main"
:END:
This is the home of my blog!
,* My Blog
:PROPERTIES:
:EXPORT_HUGO_SECTION: posts
:END:
,** My Blog Homepage
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_FILE_NAME: _index
:END:
Man, look at all my blog posts.
,** I have herpes
:PROPERTIES:
:EXPORT_FILE_NAME: herpes
:END:
Someone gave me herpes! Oh no!
#+end_src
Which yields the following:
#+begin_src
.
├── content
│ ├── _index.md
│ └── posts
│ ├── herpes.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!
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).
To illustrate, let's assume you want to extend the previous site definition with
a section about fishsticks.
#+begin_src org -n 24
,* Fishsticks
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_HUGO_SECTION: fishsticks
: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
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:
#+begin_src
.
├── content
│ ├── fishsticks
│ │ ├── gortons.md
│ │ ├── _index.md
│ │ └── van-de-camps.md
│ ├── _index.md
│ └── posts
│ ├── herpes.md
│ └── _index.md
└── hugotest.org
#+end_src
But on inspection of the gortons.md file, we find the anomoly mentioned above:
#+begin_src markdown -n
---
title: "Gortons"
author: ["Ken Grimes"]
draft: false
menu:
main:
weight: 2002
identifier: "gortons"
---
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.
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.
*** Hugo Setup
At this point, setting up Hugo and publishing is simple. [[https://gohugo.io/getting-started/installing/][Installing]] Hugo is
pretty straightforward on any Unix-like system with a package manager; it is
available on most distributions at this point. Windows installation is a bigger
pain in the ass, but you should be used to that if you're still in the
stone-age.
Using ~hugo new site .~ on the command-line will create a new hugo site in the
current directory, but ~hugo~ expects to be creating a new directory with this
command and will complain if it already exists. It also provides the ~--force~
option to allow creating a new site in an extant directory, but this too will
fail if the *content* subdirectory already exists (which ox-hugo will create
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
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.
It's convenient to do this through the ~hugo~ command because it will create
Hugo-specific subdirectories like archetypes, layouts, themes, etcetera, in
addition to populating a basic *config.toml* file. The subdirectories it creates
aren't necessary, but help illustrate Hugo's structure. In any case, you'll want
to wind up with a directory structure something like this (created with option 2
above, extending from previous examples):
#+begin_src
.
├── archetypes
│ └── default.md
├── config.toml
├── content
├── data
├── hugotest.org
├── layouts
├── static
└── themes
#+end_src
Exporting with ox-hugo using ~C-c C-e H A~ again will, as expected, fill the
content directory with our content.
#+begin_src
.
├── archetypes
│ └── default.md
├── config.toml
├── content
│ ├── fishsticks
│ │ ├── gortons.md
│ │ ├── _index.md
│ │ └── van-de-camps.md
│ ├── _index.md
│ └── posts
│ ├── herpes.md
│ └── _index.md
├── data
├── hugotest.org
├── layouts
├── static
└── themes
#+end_src
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.
#+begin_src
.
├── archetypes
│ └── default.md
├── config.toml
├── content
│ ├── fishsticks
│ │ ├── gortons.md
│ │ ├── _index.md
│ │ └── van-de-camps.md
│ ├── _index.md
│ └── posts
│ ├── herpes.md
│ └── _index.md
├── data
├── hugotest.org
├── layouts
├── public
│ ├── categories
│ │ └── index.xml
│ ├── fishsticks
│ │ └── index.xml
│ ├── index.xml
│ ├── posts
│ │ └── index.xml
│ ├── sitemap.xml
│ └── tags
│ └── index.xml
├── static
└── 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:
#+begin_src org -n
#+hugo_base_dir: .
,* My Homepage
:PROPERTIES:
:EXPORT_HUGO_SECTION:
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_MENU: :menu "main"
:END:
This is the home of my blog!
,* My Blog
:PROPERTIES:
:EXPORT_HUGO_SECTION: posts
:END:
,** 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:
:PROPERTIES:
:EXPORT_FILE_NAME: herpes
:END:
Someone gave me herpes! Oh no!
,* Fishsticks
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_HUGO_SECTION: fishsticks
:EXPORT_FILE_NAME: _index
:END:
This section devoted to Orson Wells, R.I.P.
,** Van De Camps :@inanity:
:PROPERTIES:
:EXPORT_FILE_NAME: van-de-camps
:END:
If this is fish, I'll be a monkey's uncle.
,** Gortons :@inanity: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
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
Tags on My New Hugo Site
http://example.org/tags/
Recent content in Tags on My New Hugo SiteHugo -- gohugo.ioen-usFear
http://example.org/tags/fear/
Mon, 01 Jan 0001 00:00:00 +0000http://example.org/tags/fear/Herpes
http://example.org/tags/herpes/
Mon, 01 Jan 0001 00:00:00 +0000http://example.org/tags/herpes/
#+end_src
And public/tags/fear/index.xml looks like this:
#+begin_src xml -n
Fear on My New Hugo Site
http://example.org/tags/fear/
Recent content in Fear on My New Hugo SiteHugo -- gohugo.ioen-usI have herpes
http://example.org/posts/herpes/
Mon, 01 Jan 0001 00:00:00 +0000http://example.org/posts/herpes/Someone gave me herpes! Oh no!Van De Camps
http://example.org/fishsticks/van-de-camps/
Mon, 01 Jan 0001 00:00:00 +0000http://example.org/fishsticks/van-de-camps/If this is fish, I’ll be a monkey’s uncle.
#+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:
#+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
└── tags
├── fear
│ ├── index.html
│ └── index.xml
├── herpes
│ ├── index.html
│ └── index.xml
├── 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.
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
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
this point you've got a fully functional blog publishing workflow from start to
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
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
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]
: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
:END:
ox-hugo is an [[http://en.wikipedia.org/wiki/Emacs][Emacs]] package for [[http://en.wikipedia.org/wiki/org-mode][org-mode]] that produces input for the static
content generator [[https://gohugo.io/][Hugo]], which I use for this website. Today I integrated its
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]]
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
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
:EXPORT_HUGO_MENU: :menu "main"
:EXPORT_HUGO_SECTION: forth
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :heading "Highly Factored Code"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/forth.png
:END:
This is where I post my watForth programs.
* Code Repositories
:PROPERTIES:
:EXPORT_FILE_NAME: _index
:EXPORT_HUGO_MENU: :menu "main" :title Git
:EXPORT_HUGO_SECTION: git
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :header /img/git.png
:END:
* About
:PROPERTIES:
:EXPORT_HUGO_SECTION: about
:EXPORT_HUGO_MENU: :menu "main" :title About
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :heading '("Ken Grimes" "Computer Scientist" "At Large")
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/home.png
:EXPORT_FILE_NAME: _index
:END:
Hi! I'm Ken, a 34-year-old computer scientist currently living in Irvine,
California. This is a website I've constructed for the purpose of developing
web-facing software. I will probably blog with it once development is
complete. In the mean time, if you're curious, this is my [[file:static/cv.pdf][curriculum vitae]]
* 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
* [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
* * *
Overview
Philosophy
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.
Inline HTML
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. `
`,
`
`, `
`, `
`, 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) `
` tags around HTML block-level tags.
For example, to add an HTML table to a Markdown article:
This is a regular paragraph.
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]: "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:
I get 10 times more traffic from Google than from
Yahoo
or MSN.
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.
Emphasis
Markdown treats asterisks (`*`) and underscores (`_`) as indicators of
emphasis. Text wrapped with one `*` or `_` will be wrapped with an
HTML `` tag; double `*`'s or `_`'s will be wrapped with an HTML
`` tag. E.g., this input:
*single asterisks*
_single underscores_
**double asterisks**
__double underscores__
will produce:
single asteriskssingle underscoresdouble asterisksdouble underscores
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\*
Code
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:
Use the printf() function.
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:
There is a literal backtick (`) here.
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:
A single backtick in a code span: `
A backtick-delimited string in a code span: `foo`
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 `