X-Git-Url: https://www.kengrimes.com/gitweb/?p=kengrimes.com%2Fcontent.git;a=blobdiff_plain;f=content.org;h=714e4f063bee59f3b96d75773a4a08949af13a38;hp=2ef879c87cff10dd494dc5b26972faf23283a30c;hb=HEAD;hpb=e3a89daeb6e4daa3240e594e6afea212b07b84cf diff --git a/content.org b/content.org index 2ef879c..714e4f0 100644 --- a/content.org +++ b/content.org @@ -1,977 +1,740 @@ #+hugo_base_dir: . #+hugo_level_offset: 0 #+seq_todo: TODO DRAFT DONE - -#+startup: indent showeverything - -#+author: Ken Grimes +#+startup: indent showall * Home :PROPERTIES: :EXPORT_HUGO_SECTION: :END: -** Blog +** Computers are the Devil :PROPERTIES: -:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :caption '("A Nonnormative Tomorrow") -:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/blog.png +:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :header /img/blog.png :EXPORT_FILE_NAME: _index -:EXPORT_HUGO_MENU: :menu "main" :weight -1 +: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-19 Thu 18:06] +:PROPERTIES: +:EXPORT_FILE_NAME: ox-hugo-tutorial +:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :header /img/org.png :END: -** DONE Another topic -CLOSED: [2018-04-05 Thu 18:29] +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]] 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, +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 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_HUGO_CUSTOM_FRONT_MATTER: :caption "Just Another Topic" -:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header /img/ox-hugo.png -:EXPORT_FILE_NAME: another-topic +:EXPORT_FILE_NAME: ox-hugo-tutorial +:EXPORT_DESCRIPTION: Exporting to Hugo's Blackfriday Markdown from Orgmode +:EXPORT_HUGO_IMAGES: /img/org.png :END: -This is just another topic, don't worry about it. - -** DONE ox-hugo :org:emacs:hugo:markdown:@blogging: -CLOSED: [2018-04-04 Wed 18:29] +#+end_src +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: . +,* My Blog +:PROPERTIES: +:EXPORT_HUGO_SECTION: +:END: +,** Home +:PROPERTIES: +:EXPORT_FILE_NAME: _index +:END: +This is the home of my blog! +,** One Bad Night +:PROPERTIES: +: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 ~#+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 +â  âââ bad-night.md +â  âââ _index.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: . +,* Homepage +:PROPERTIES: +:EXPORT_HUGO_SECTION: +:EXPORT_FILE_NAME: _index +:EXPORT_HUGO_MENU: :menu "main" +:END: +This is the home of my blog! +,* Blog Posts +: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. +,** One Bad Night +:PROPERTIES: +:EXPORT_FILE_NAME: bad-night +:END: +Someone gave me herpes! Oh no! +#+end_src +Which yields the following files on export: +#+begin_src +. +âââ content +â  âââ _index.md +â  âââ posts +â  âââ bad-night.md +â  âââ _index.md +âââ hugotest.org +#+end_src +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 +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 ~