You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
207 lines
11 KiB
207 lines
11 KiB
#+TITLE: Ox-Hugo: A carefully crafted Org exporter back-end for Hugo |
|
#+AUTHOR: Kaushal Modi |
|
[[https://travis-ci.org/kaushalmodi/ox-hugo][https://travis-ci.org/kaushalmodi/ox-hugo.svg?branch=master]] [[https://melpa.org/#/ox-hugo][file:https://melpa.org/packages/ox-hugo-badge.svg]] [[https://www.gnu.org/licenses/gpl-3.0][https://img.shields.io/badge/License-GPL%20v3-blue.svg]] [[https://gitter.im/KaushalModi/Lobby][https://badges.gitter.im/KaushalModi/Lobby.svg]] |
|
=ox-hugo= is an Org exporter backend that exports Org to |
|
[[https://gohugo.io/][Hugo]]-compatible Markdown ([[https://github.com/russross/blackfriday][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 [[https://github.com/larstvei/ox-gfm][=ox-gfm=]] with support added for Blackfriday Markdown tables and |
|
many other tweaks. =ox-hugo= backend extends from this. |
|
* Table of Contents |
|
- [[#screenshots][Screenshots]] |
|
- [[#documentation][Documentation]] |
|
- [[#source-of-the-documentation-site][Source of the Documentation site]] |
|
- [[#demo][Demo]] |
|
- [[#actual-usage-examples][Actual usage examples]] |
|
- [[#installation][Installation]] |
|
- [[#usage][Usage]] |
|
- [[#before-you-export][Before you export]] |
|
- [[#export-bindings][Export bindings]] |
|
- [[#customization-options][Customization Options]] |
|
- [[#changelog][Changelog]] |
|
- [[#thanks][Thanks]] |
|
|
|
* 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 (preferred) |
|
[[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/static/images/one-post-per-subtree.png][https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/static/images/one-post-per-subtree.png]] |
|
- Files in above screenshot :: [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/screenshot-subtree-export-example.org][Org]] -> [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content/writing-hugo-blog-in-org-subtree-export.md][Markdown]] |
|
** One post per Org file |
|
[[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/static/images/one-post-per-file.png][https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/static/images/one-post-per-file.png]] |
|
- Files in above screenshot :: [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content-org/writing-hugo-blog-in-org-file-export.org][Org]] -> [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/test/site/content/writing-hugo-blog-in-org-file-export.md][Markdown]] |
|
** Editorial |
|
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. |
|
* Documentation |
|
=ox-hugo= uses *itself* to generate its documentation! |
|
|
|
https://ox-hugo.scripter.co/ |
|
|
|
You can generate the same too! Simply clone this repo and do =make |
|
doc=. |
|
*Make sure you visit the above link to read more on:* |
|
- [[https://ox-hugo.scripter.co/doc/why-ox-hugo/][Why =ox-hugo=?]] |
|
- [[https://ox-hugo.scripter.co/doc/auto-export-on-saving/][Auto exporting to Markdown each time the Org file is saved]] |
|
- [[https://ox-hugo.scripter.co/doc/org-capture-setup/][Using Org Capture to start a new blog post]] |
|
- .. and many more topics and examples |
|
** Source of the Documentation site |
|
- [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/master/doc/ox-hugo-manual.org][Org source]] |
|
- =ox-hugo= exported [[https://github.com/kaushalmodi/ox-hugo/tree/master/doc/content][Markdown files]] |
|
|
|
* Demo |
|
[[https://github.com/kaushalmodi/ox-hugo/tree/master/test/site/content-org][Org source]] → [[https://github.com/kaushalmodi/ox-hugo/tree/master/test/site/content][Exported Markdown]] → [[file:../test][*Hugo published test site*]] |
|
|
|
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 [[https://github.com/kaushalmodi/ox-hugo/tree/master/test/site/themes/bare_min/][*bare_min*]] /theme/ written just for the debug purpose (not |
|
presentation). |
|
/See [[https://themes.gohugo.io/][Hugo Themes]] for examples of really good site prettification and |
|
presentation styles./ |
|
** Actual usage examples |
|
- https://ox-hugo.scripter.co -- =ox-hugo= Documentation Site |
|
- [[https://scripter.co]] -- My blog |
|
|
|
* Installation |
|
This package requires emacs 24.5+ and Org 9.0+. It is available on |
|
Melpa ([[https://melpa.org/#/ox-hugo]]). |
|
* 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: |
|
#+BEGIN_SRC emacs-lisp |
|
(with-eval-after-load 'ox |
|
(require 'ox-hugo)) |
|
#+END_SRC |
|
If you use =use-package=, you can do the below instead: |
|
#+BEGIN_SRC emacs-lisp |
|
(use-package ox-hugo |
|
:after ox) |
|
#+END_SRC |
|
*Spacemacs* |
|
|
|
Spacemacs users can choose to add this snippet to their |
|
=dotspacemacs/user-config= function in =.spacemacs=: |
|
|
|
#+BEGIN_SRC emacs-lisp |
|
(defun dotspacemacs/user-config () |
|
;; Other stuff |
|
;; .. |
|
|
|
;; ox-hugo config |
|
(use-package ox-hugo |
|
:ensure t ;Auto-install the package from Melpa |
|
:after ox)) |
|
#+END_SRC |
|
|
|
If you do so, you *also need to* add =ox-hugo= to |
|
=dotspacemacs-additional-packages=. |
|
/Verified to work on Spacemacs =develop= branch with =spacemacs-base= |
|
distribution, =emacs= editing style./ |
|
** 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 |
|
[[http://gohugo.io/content/sections/][here]] 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 ([[http://gohugo.io/content/organization/][ref]]). If you try to export without |
|
setting this property, you will get this error: |
|
#+BEGIN_EXAMPLE |
|
user-error: It is mandatory to set the HUGO_BASE_DIR property |
|
#+END_EXAMPLE |
|
*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 |
|
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 | |
|
|---------------+-------------------------------------------------------------------------------------| |
|
** Customization Options |
|
Do =M-x customize-group=, and select =org-export-hugo= to see the |
|
available customization options for this package. |
|
* Changelog |
|
** 0.2.2 <2017-10-10 Tue> |
|
*** Backward-incompatible changes |
|
- Now =ox-hugo= by default requires text, to be sub/super-scripted, to |
|
be wrapped in ={}=. So now =a_b= will be exported as =a_b=, but =a_{b}= will be exported as =a<sub>b</sub>=. To revert back to the |
|
earlier behavior, user needs to add =#+OPTIONS: ^:t= to their Org |
|
file. |
|
** 0.2.1 <2017-09-28 Thu> |
|
*** Fixes |
|
- Single column tables now export correctly [[[https://github.com/kaushalmodi/ox-hugo/issues/84][84]]]. |
|
- Ignore =HUGO_WEIGHT= set to =auto= for /per-file/ exports |
|
[[[https://github.com/kaushalmodi/ox-hugo/issues/83][83]]]. |
|
** 0.2 <2017-09-27 Wed> |
|
*** Features |
|
- Add support for all Hugo =figure= shortcode parameters |
|
[[[https://github.com/kaushalmodi/ox-hugo/issues/79][79]]]. |
|
- New option =org-hugo-delete-trailing-ws= defaults to =t=; now Hugo |
|
deletes trailing white-spaces by default. |
|
- New options =org-hugo-default-static-subdirectory-for-externals= and =org-hugo-external-file-extensions-allowed-for-copying= (related to |
|
[[[https://github.com/kaushalmodi/ox-hugo/issues/69][69]]]). |
|
*** Fixes |
|
- Remove =HUGO_STATIC_IMAGE= option; fix attachment re-write |
|
[[[https://github.com/kaushalmodi/ox-hugo/issues/69][69]]]. |
|
- Fix incorrectly inserted hard line-breaks [[[https://github.com/kaushalmodi/ox-hugo/issues/72][72]]]. Added a |
|
new option =HUGO_PRESERVE_FILLING=. |
|
- Fix error happening when a post title was set to an empty string |
|
[[[https://github.com/kaushalmodi/ox-hugo/commit/ba9e8365f6ee42f030ed806bf5ec42d6acce4c76][ba9e8365]]]. |
|
*** Backward-incompatible changes |
|
- Switch the default value of =org-hugo-use-code-for-kbd= option to =nil= [[[https://github.com/kaushalmodi/ox-hugo/commit/88ba15ae9bc809b0983315446c88fecfda3534e5][88ba15ae]]]. |
|
** 0.1.3 <2017-09-13 Wed> |
|
- Now a HUGO key value set to ="nil"=, like =#+HUGO_CODE_FENCE: nil=, |
|
will evaluate as /nil/ instead of /t/, as now =org-hugo--plist-get-true-p= is used to parse boolean keys instead |
|
of =plist-get=. |
|
** 0.1.2 <2017-09-12 Tue> |
|
- Make DateTime matching better; new internal variable =org-hugo--date-time-regexp=. Earlier time zones ahead of UTC (with =+= sign) were not detected as dates in =org-hugo--quote-string= and |
|
thus were unnecessarily quoted. |
|
** 0.1.1 <2017-09-11 Mon> |
|
- Use CLOSED log drawer info if available to set the date in |
|
front-matter [[[https://github.com/kaushalmodi/ox-hugo/issues/68][68]]]. |
|
- Code optimization: Use of =org-entry-get= at places instead of |
|
maintaining global variables. |
|
* Thanks |
|
- Matt Price ([[https://github.com/titaniumbones][@titaniumbones]]) |
|
- Puneeth Chaganti ([[https://github.com/punchagan][@punchagan]]) |
|
- Also thanks to [[http://www.holgerschurig.de/en/emacs-blog-from-org-to-hugo/][holgerschurig.de]], [[http://whyarethingsthewaytheyare.com/setting-up-the-blog/][whyarethingsthewaytheyare.com]] and |
|
the [[https://github.com/chaseadamsio/goorgeous][=goorgoeous=]] project by Chase Adams ([[https://github.com/chaseadamsio][@chaseadamsio]]) for |
|
inspiration to start this project. |
|
|
|
|