X-Git-Url: https://www.kengrimes.com/gitweb/?p=kengrimes.com%2Fcontent.git;a=blobdiff_plain;f=content.org;h=714e4f063bee59f3b96d75773a4a08949af13a38;hp=9b9de65c9c908af853233998ff56e01de83a9716;hb=HEAD;hpb=137a062b4047f3eb304f4e397eb385a5f983c16f diff --git a/content.org b/content.org index 9b9de65..714e4f0 100644 --- a/content.org +++ b/content.org @@ -15,33 +15,32 @@ :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 +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 @@ -51,7 +50,7 @@ the reader even if they're unfamiliar with the formal syntax. For instance, | 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 | @@ -59,68 +58,72 @@ Produces a dynamic spreadsheet table in org-mode that exports to HTML like this: | 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 -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 +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 @@ -129,14 +132,14 @@ 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 +,* 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: @@ -146,55 +149,65 @@ This is the home of my blog! :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 ~