X-Git-Url: https://git.kengrimes.com/?p=kengrimes.com%2Fcontent.git;a=blobdiff_plain;f=content.org;h=e655e076f0ddbad883b1c7e8c27ea5a6468aa947;hp=5d2e608079bba6e6a529f55bb40e2dc641d721d0;hb=7072d757845413feff035438ec521c3c0c5ccd3a;hpb=db9c1fb782bf9a69aba450da4b0541753ef6eba7 diff --git a/content.org b/content.org index 5d2e608..e655e07 100644 --- a/content.org +++ b/content.org @@ -15,11 +15,10 @@ :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 @@ -75,52 +74,56 @@ Eventually you'll want to [[https://orgmode.org/manual/][read the manual]], thou 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 @@ -129,88 +132,99 @@ 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 +,* 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 ~