Publish documentation using Hugo

Get rid of the Github Wiki

Makefile

@@ -1,4 +1,4 @@
-# Time-stamp: <2017-09-22 10:47:04 kmodi>
+# Time-stamp: <2017-09-22 17:07:48 kmodi>
 
 # Makefile to export org documents to md for Hugo from the command line
 # Run just "make" to see usage examples.
@@ -21,7 +21,7 @@ OX_HUGO_TEST_SITE_DIR=$(OX_HUGO_TEST_DIR)/site
 OX_HUGO_TEST_ORG_DIR=$(OX_HUGO_TEST_SITE_DIR)/content-org
 
 # Path to the Org file relative to $(OX_HUGO_TEST_ORG_DIR)
-ORG=
+ORG_FILE=
 
 # Directory where the required elisp packages are auto-installed
 OX_HUGO_ELPA=/tmp/$(USER)/ox-hugo-dev/
@@ -47,6 +47,7 @@ file_test_files = single-posts/post-toml.org \
 	test vcheck testmkgold \
 	test_subtree $(subtree_test_files) \
 	test_file $(file_test_files) \
+	doc \
 	ctemp diffgolden clean
 
 help:
@@ -57,21 +58,23 @@ help:
 	@echo " make hugo          <-- Run hugo"
 	@echo " make serve         <-- Run the hugo server on http://localhost:$(PORT)"
 	@echo " make diff          <-- Run git diff"
+	@echo " make doc           <-- Build the Markdown content for the documentation site"
 	@echo " make test          <-- Run test"
 	@echo " make clean         <-- Delete the Hugo public/ directory and auto-installed elisp packages"
 	@echo " make               <-- Show this help"
 
-# Note: The Org file from $(ORG) is loaded *after* the --eval section
-# gets evaluated i.e. --eval '(progn ..)' $(ORG) If the order is
-# reversed i.e. i.e.$(ORG) --eval '(progn ..)', the act of loading
-# the $(ORG) file first will load the older Org version that ships
-# with Emacs and then run the stuff in --eval that loads the new Org
-# version.. and thus we'll end up with mixed Org in the load-path.
+# Note: The Org file from $(ORG_FILE) is loaded *after* the --eval
+# section gets evaluated i.e. --eval '(progn ..)' $(ORG_FILE) If the
+# order is reversed i.e. i.e.$(ORG_FILE) --eval '(progn ..)', the act
+# of loading the $(ORG_FILE) file first will load the older Org
+# version that ships with Emacs and then run the stuff in --eval that
+# loads the new Org version.. and thus we'll end up with mixed Org in
+# the load-path.
 emacs-batch:
 	@$(EMACS) --batch --eval "(progn\
 	(setenv \"OX_HUGO_ELPA\" \"$(OX_HUGO_ELPA)\")\
 	(load-file (expand-file-name \"setup-ox-hugo.el\" \"$(OX_HUGO_TEST_DIR)\"))\
-	)" $(OX_HUGO_TEST_ORG_DIR)/$(ORG) \
+	)" $(ORG_FILE_DIR)/$(ORG_FILE) \
 	-f $(FUNC) \
 	--kill
 
@@ -120,17 +123,22 @@ testmkgold:
 # https://stackoverflow.com/a/37748952/1219634
 test_subtree: $(subtree_test_files)
 $(subtree_test_files):
-	@$(MAKE) mdtree ORG=$@
+	@$(MAKE) mdtree ORG_FILE=$@ ORG_FILE_DIR=$(OX_HUGO_TEST_ORG_DIR)
 	@$(MAKE) diffgolden
 
 # Run the mdfile + diffgolden rules in loop on all of $(file_test_files)
 test_file: $(file_test_files)
 $(file_test_files):
-	@$(MAKE) mdfile ORG=$@
+	@$(MAKE) mdfile ORG_FILE=$@ ORG_FILE_DIR=$(OX_HUGO_TEST_ORG_DIR)
 	@$(MAKE) diffgolden
 
+doc:
+	@$(MAKE) mdtree ORG_FILE=ox-hugo-manual.org ORG_FILE_DIR=./doc
+	@$(MAKE) ctemp
+
 ctemp:
 	@find $(OX_HUGO_TEST_SITE_DIR)/content -name "*.*~" -delete
+	@find ./doc/content -name "*.*~" -delete
 
 diffgolden: ctemp
 	@diff -r $(OX_HUGO_TEST_SITE_DIR)/content $(OX_HUGO_TEST_SITE_DIR)/content-golden

doc/config.toml

@@ -0,0 +1,95 @@
+baseURL = "http://example.org/"
+
+Title = "ox-hugo - Org to Hugo exporter"
+theme = "hugo-alabaster-theme"
+
+contentdir = "content"
+layoutdir = "layouts"
+publishdir = "public"
+
+# Remove files from destination not found in static directories
+cleandestinationdir = true
+
+# Needed for relative references like in the below image link
+#   ![Example PNG image](/images/org-mode-unicorn-logo.png)
+canonifyURLs = true
+enableGitInfo = true
+
+# https://gohugo.io/extras/highlighting/
+
+# Syntax highlighting using Pygments
+# $ python
+# >>> from pygments.styles import STYLE_MAP
+# >>> STYLE_MAP.keys()
+# ['manni', 'igor', 'lovelace', 'xcode', 'vim', 'autumn', 'vs', 'rrt', 'native',
+# 'perldoc', 'borland', 'tango', 'emacs', 'friendly', 'monokai', 'paraiso-dark',
+# 'colorful', 'murphy', 'bw', 'pastie', 'algol_nu', 'paraiso-light', 'trac',
+# 'default', 'algol', 'fruity']
+# pygmentsStyle = "native"
+pygmentsStyle = "trac"
+pygmentsCodeFences = true
+# Use pygmentize generated CSS file instead of inlining the code codes in the HTML.
+# See https://gohugo.io/tools/syntax-highlighting/#pygments and
+# https://github.com/richleland/pygments-css
+pygmentsUseClasses = true
+
+# Fri Sep 22 15:50:42 EDT 2017 - kmodi
+# Disabling Emoji otherwise the ":abc:" portion in `* foo :abc:def:`
+# renders to an Emoji!
+enableEmoji = false
+
+LanguageCode = "en-us" # Used in RSS generation
+
+[Permalinks]
+  # post = "/:year/:month/:title/"
+  # Below, we have
+  #   foo = "bar"
+  # where foo = section name without double quotes for which we want to have
+  # the custom permalinks. If foo is 'posts', it will apply to content in
+  # content/posts/ dir. The "bar" portion is how you want the links to look.
+  doc = "/doc/:slug/"
+  test = "/test/:slug/"
+
+[params]
+  name = "ox-hugo"
+  description = "Org mode to Hugo exporter<br />Write your Hugo posts in native Org mode."
+
+  # Go date formats: https://golang.org/pkg/time/#pkg-constants
+  dateform = "Mon Jan 2, 2006"
+
+  github_user = "kaushalmodi"
+  github_repo = "ox-hugo"
+  github_banner = true
+
+  custom_css = [ "css/style.css"
+                 # Pygments Trac theme
+                 , "css/trac_pygments.css"
+               ]
+  custom_css_absolute = [ # Iosevka fonts
+                          "https://cdn.rawgit.com/kaushalmodi/iosevka-mirror/v1.13.2/iosevka.css"
+                        ]
+  custom_js  = []
+
+  # highlightjs = "css/highlight.css"
+  # favicon = "favicon.ico"
+
+[params.sidebar]
+  logo = "favicon.ico"
+
+  github_button  = true
+  travis_button  = true
+  codecov_button = false
+  gratipay = ""
+
+  # Mon Sep 04 23:55:36 EDT 2017 - kmodi
+  # Disable this option for now.. but seems to be useful in future
+  show_relations = false
+
+[params.footer]
+  copyright = ""
+  show_powered_by = true
+
+# Blackfriday is Hugo's markdown engine.
+# https://gohugo.io/overview/configuration/#configure-blackfriday-rendering
+[blackfriday]
+  hrefTargetBlank = true # open external links in a new window or tab

doc/content/_index.md

@@ -0,0 +1,139 @@
++++
+title = "Org to Markdown for Hugo"
+type = "homepage"
+draft = false
+[menu.main]
+  weight = 1001
+  identifier = "org-to-markdown-for-hugo"
++++
+
+`ox-hugo` is an Org exporter backend that exports Org to
+[Hugo](https://gohugo.io/)-compatible Markdown ([Blackfriday](https://github.com/russross/blackfriday)) and also generates the
+front-matter (in TOML or YAML format).
+
+This project consists of `ox-blackfriday.el` too. It is a derivation
+of [`ox-gfm`](https://github.com/larstvei/ox-gfm) with support added for Blackfriday Markdown tables and
+many other tweaks. `ox-hugo` backend extends from this.
+
+
+## Screenshots {#screenshots}
+
+Before you read further, you can see below how `ox-hugo` translates
+Org to Markdown (Org on the left; exported Markdown with Hugo
+front-matter on the right).
+
+**One post per Org subtree --**
+[{{<figure src="/images/one-post-per-subtree.png">}}](/images/one-post-per-subtree.png)
+
+-   **Files in above screenshot:** [Org](https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/screenshot-subtree-export-example.org) -> [Markdown](https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content/writing-hugo-blog-in-org-subtree-export.md)
+
+**One post per Org file --**
+[{{<figure src="/images/one-post-per-file.png">}}](/images/one-post-per-file.png)
+
+-   **Files in above screenshot:** [Org](https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/writing-hugo-blog-in-org-file-export.org) -> [Markdown](https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content/writing-hugo-blog-in-org-file-export.md)
+
+The preferred way to organize the posts is as Org subtrees (also the
+main reason to write this package, as nothing like that was out there)
+as it makes the meta-data management for Hugo front-matter pretty
+effortless.
+
+If you are a _one Org-file per post_ type of a person, that flow works
+too! Just note that in this flow many of those `#+HUGO_` properties
+need to be managed manually.. just as one would manage the front-matter
+in Markdown files --- See the Org versions in the above screenshots for
+comparison.
+
+
+## Demo {#demo}
+
+[Org source](https://github.com/kaushalmodi/ox-hugo/tree/master/test/site/content-org) → [Exported Markdown](https://github.com/kaushalmodi/ox-hugo/tree/master/test/site/content) → [**Hugo published test site**](../test)
+
+Now, the test site doesn't look pretty, I know :) .. because:
+
+-   It is designed to verify if all the content translates from Org to
+    Markdown as expected.
+-   It uses a [**bare\_min**](https://github.com/kaushalmodi/ox-hugo/tree/master/test/site/themes/bare_min/) _theme_ written just for the debug purpose (not
+    presentation).
+
+_See [Hugo Themes](https://themes.gohugo.io/) for examples of really good site prettification and
+presentation styles._
+
+
+### Actual usage examples {#actual-usage-examples}
+
+-   <https://ox-hugo.netlify.com> -- `ox-hugo` Documentation Site
+-   <https://scripter.co> -- My blog
+
+
+## Installation {#installation}
+
+This package requires emacs 24.5+ and Org 9.0+. It is available on
+Melpa (<https://melpa.org/#/ox-hugo>).
+
+
+## Usage {#usage}
+
+Once the package is installed, you will need to require it so that the
+`ox-hugo` export options are available in the _Org Export Dispatcher_
+menu (the one you see when you hit `C-c C-e` to initiate any export).
+
+You can do that by adding the below to your config:
+
+```emacs-lisp
+(with-eval-after-load 'ox
+  (require 'ox-hugo))
+```
+
+If you use `use-package`, you can do the below instead:
+
+```emacs-lisp
+(use-package ox-hugo
+  :after ox)
+```
+
+
+### Before you export {#before-you-export}
+
+Before you export check that these properties are set as you need:
+
+-   **HUGO\_SECTION:** The default Hugo section name for all the posts.  See
+    [here](http://gohugo.io/content/sections/) for more information on Hugo sections.  It is
+    common for this property to be set to `posts` or
+    `blog`.  The default value is set using
+    `org-hugo-default-section-directory`.
+-   **HUGO\_BASE\_DIR:** Root directory of the source for the Hugo site. If
+    this is set to `~/hugo/`, the exported Markdown
+    files will be saved to
+    `~/hugo/content/<HUGO_SECTION>/` directory.  By
+    default, the Markdown files reside in a hierarchy
+    under the `content/` directory in the site root
+    directory ([ref](http://gohugo.io/content/organization/)). If you try to export without
+    setting this property, you will get this error:
+
+    ```text
+    user-error: It is mandatory to set the HUGO_BASE_DIR property
+    ```
+
+**Important**: If you choose to export an Org subtree as a post, you
+ need to set the `EXPORT_FILE_NAME` subtree property. That property is
+ used by this package to figure out where the current post starts.
+
+
+### Export bindings {#export-bindings}
+
+The common `ox-hugo` export bindings are:
+
+Binding       | Description
+--------------|--------------------------------------------------------------------------------------
+`C-c C-e H H` | Export only the current _valid_ subtree (has the `EXPORT_FILE_NAME` property set)
+`C-c C-e H A` | Export **all** _valid_ subtrees (those that have the `EXPORT_FILE_NAME` property set)
+`C-c C-e H h` | Export the whole Org file to a single post
+
+
+## Thanks {#thanks}
+
+-   Matt Price ([@titaniumbones](https://github.com/titaniumbones))
+-   Puneeth Chaganti ([@punchagan](https://github.com/punchagan))
+-   Also thanks to [holgerschurig.de](http://www.holgerschurig.de/en/emacs-blog-from-org-to-hugo/), [whyarethingsthewaytheyare.com](http://whyarethingsthewaytheyare.com/setting-up-the-blog/) and
+    the [`goorgoeous`](https://github.com/chaseadamsio/goorgeous) project by Chase Adams ([@chaseadamsio](https://github.com/chaseadamsio)) for
+    inspiration to start this project.