wilderjds
/
ox-hugo
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
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.
398 Commits
1 Branch
0 Tags
6.6 MiB
 
 
 
 
Tag: Branch: Tree: e86ab6ad21
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'e86ab6ad21'
${ noResults }
ox-hugo/README.org

343 lines
18 KiB
Raw Blame History

#+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]] [[https://saythanks.io/to/kaushalmodi][https://img.shields.io/badge/Say%20Thanks-!-1EAEDB.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_md=.
*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]]
The documentation site is published by first using =ox-hugo= to
export from Org to Markdown, and then finally =hugo=.
/So no Markdown files are committed in the =doc/content/= directory./
* 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][=ox-hugo= Exported Markdown]] → https://ox-hugo.scripter.co/test
Now, the test site looks very simple, 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
extra aesthetics).
/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:
*** For both one-post-per-subtree and one-post-per-file flows
- =C-c C-e H H= :: Export "What I Mean".
- If point is in a /valid Hugo post subtree/, export that
subtree to a Hugo post in Markdown.
A /valid Hugo post subtree/ is an Org subtree has the =EXPORT_FILE_NAME= property set.
- If the file is intended to be exported as a whole i.e. it must have
the #+TITLE keyword set, export the whole Org file a Hugo post in
Markdown.
- =C-c C-e H A= :: Export *all* "What I Mean"
- If the Org file has one or more 'valid Hugo post subtrees', export
them to Hugo posts in Markdown.
- If the file is intended to be exported as a whole (no 'valid Hugo
post subtrees' at all) i.e. it must have the #+TITLE keyword set,
export the whole Org file a Hugo post in Markdown.
*** For only the one-post-per-file flow
- =C-c C-e H h= :: Export the Org file to a Hugo post in Markdown.
** Customization Options
Do =M-x customize-group=, and select =org-export-hugo= to see the
available customization options for this package.
* Changelog
** v0.6 <2017-11-09 Thu>
*** Features
- Support the =num= export option. Now you can prefix all post
headings (or some not.. the ones with =UNNUMBERED= property set to =t=) with their section numbers --- [[[https://github.com/kaushalmodi/ox-hugo/issues/76][76]]].
- Org TOC's are now exported as unordered Markdown lists. This allows
having TOC's with unnumbered headings too! This also enables
prefixing the section headings with their full section numbers, and
also having only selected headings unnumbered (both in the post body
and the TOC).
- Add support for exporting internal links to source blocks, tables
and images by their block names! -- [[[https://github.com/kaushalmodi/ox-hugo/issues/29][29]]].
- Org table column alignment markers (=<l>=, =<r>=, =<c>=) are now
exported to equivalent Markdown tables.. so a center-aligned column
in Org buffer will remain center-aligned in the final HTML too! --
[[[https://github.com/kaushalmodi/ox-hugo/issues/95][95]]].
- Allow setting multiple Hugo aliases for a post. Also infer the
section name from inherited =HUGO_SECTION= values (subtree-based
exports) for those alias prefixes.
- Prevent a footnote ref to appear by itself on a newline (based on
wrapping) in the browser -- [[[https://github.com/kaushalmodi/ox-hugo/issues/96][96]]].
- If Hugo shortcodes are used specifically in Markdown (=md=) source
blocks, they will be auto-escaped (useful when you want to
document/talk about some Hugo shortcode in a blog post) --
[[[https://github.com/kaushalmodi/ox-hugo/issues/94][94]]].
- If an Org table has just 1 row, don't make it render as a header row
in the final HTML.
- If you have a case where you need to have an Org source block
instead a quote block, and then a source block after that quote
block (/I know, a very common case../ :wink:), Blackfriday barfs
(Blackfriday # [[https://github.com/russross/blackfriday/issues/407][407]]). But we now have a workaround, which /just
works/ -- [[[https://github.com/kaushalmodi/ox-hugo/issues/98][98]]].
- Now =ATTR_HTML= above even hyper-linked images works (earlier it
worked only above non-hyper-linked images).
*** Backward-incompatible changes
- Org TOC's are exported as unordered Markdown lists instead of
ordered Markdown lists, and now full section numbers (like 1.2.3)
are shown in the TOC instead of just the last digit (like 3.) --
commit [[https://github.com/kaushalmodi/ox-hugo/commit/4be378e7][4be378e7]].
- The =num= Org export option is default to =nil= (only for =ox-hugo=). So Org TOC's are exported without section numbers by
default. To get section numbers, set =num= to =t= or =onlytoc=.
*** Fixes
- Now exporting 1-row Org tables works too.
- Add missing http/https/ftp prefix for hyper-linked images.
*** Meta
- Add documentation on how you can have
[[https://ox-hugo.scripter.co/doc/images-in-content][Images live in the same directory as Org
source]] -- [[[https://github.com/kaushalmodi/ox-hugo/issues/91][91]]].
- Now only Org files for the [[https://ox-hugo.scripter.co][documentation site]] need to be committed
to git. =ox-hugo= then exports those to Markdown, and then Hugo
publishes those to HTML (as before) --- all on Netlify.
- Be sure to check out the moderately revamped [[https://ox-hugo.scripter.co/test/][Test Site]]. That might
be of interest even if you want to check out what the new features
and changes look like, without first installing/updating =ox-hugo=
yourself :smile:.
** v0.5 <2017-11-06 Mon>
*** Features
- Export TOC as a Markdown ordered list. See [[https://ox-hugo.scripter.co/doc/org-toc][Table of
Contents]] -- [[[https://github.com/kaushalmodi/ox-hugo/issues/88][88]]].
- =#+ATTR_HTML= above http/https/ftp links is now supported (useful
for specifying the =target=, =rel=, attributes, for example).
** v0.4.1 <2017-10-29 Sun>
*** Features
- Support specifying the =:height= parameter in the =#+ATTR_HTML=
above image links. That eventually gets transformed to the =height=
parameter in the =figure= tag in the HTML generated by Hugo. This
feature requires building Hugo from its master branch with commit
[[https://github.com/gohugoio/hugo/commit/488631fe0abc3667355345c7eb98ba7a2204deb5][488631fe]] (or Hugo v0.31+).
*** Fixes
- Fix =EXPORT_HUGO_SECTION= not getting inherited [[[https://github.com/kaushalmodi/ox-hugo/issues/90][90]]].
** v0.4 <2017-10-28 Sat>
*** Backward-incompatible changes
- Restore the default Org behavior of =#+TAGS=. Now that keyword (and
the =EXPORT_TAGS= property) is *not* used by =ox-hugo=. Fixes
[[[https://github.com/kaushalmodi/ox-hugo/issues/89][89]]].
- File-based exports must now use =#+HUGO_TAGS= to set the post tags.
- Subtree-based exports can use the =EXPORT_HUGO_TAGS= property to
override Org-style tags on the same headline (and the ones inherited
from Org-style tags from any of the parent subtrees and =#+FILETAGS=).
- Note that for subtree-based exports, =#+FILETAGS= can be used to
set tags globally in the file. Earlier =#+TAGS= was used for that
purpose.
- Subtree-based exports can use the =EXPORT_HUGO_CATEGORIES= property
to override Org-style categories (tags with "@" prefix) on the same
headline (and the ones inherited from Org-style categories from any
of the parent subtrees and =#+FILETAGS=).
- Note that for subtree-based exports, =#+FILETAGS= can be used to
set categories (tags with "@") globally in the file.
See the new section added to documentation:
[[https://ox-hugo.scripter.co/doc/tags-and-categories][*Tags and Categories*]]
*** Features
- Support specifying the =:width= parameter in the =#+ATTR_HTML= above
image links. That eventually gets transformed to the =width=
parameter in the =figure= tag in the HTML generated by Hugo.
** v0.3.2 <2017-10-24 Tue>
*** Fixes
- Fix issue with headline metadata parsing (ALLTAGS, CLOSED, TODO)
when a post Org heading was immediately followed by that post's
sub-heading. This issue was seen in subtree-based exports
[[[https://github.com/kaushalmodi/ox-hugo/issues/87][87]]].
** v0.3.1 <2017-10-19 Thu>
*** Fixes
- Fix the source block line number annotation when the line numbers
increased in number of digits in the same code block.
** v0.3 <2017-10-18 Wed>
*** Features
- Source blocks can now be exported with line numbers and/or
highlighting!
See [[https://ox-hugo.scripter.co/doc/source-blocks][Source Blocks]] for details.
** v0.2.3 <2017-10-11 Wed>
*** Fixes
- =org-hugo-slug= earlier stripped off only the =code= HTML tag
(~<code> .. </code>~) from the input string, if present. Now it does
that for *any* HTML tag, like =span=. For example, this HTML gets
stripped off from the above heading (only inside =org-hugo-slug=
when deriving the slug string): ~<span
class="timestamp-wrapper"><span class="timestamp">&lt;2017-10-11
Wed&gt;</span></span>~.
** v0.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.
** v0.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]]].
** v0.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]]].
** v0.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=.
** v0.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.
** v0.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][=goorgeous=]] project by Chase Adams ([[https://github.com/chaseadamsio][@chaseadamsio]]) for
inspiration to start this project.