Blogging with org-mode and jekyll without alien yaml headers.
- Remove deprecated api function names mentioned in 0.1.2 -> 0.1.4 migration.
- Permit user to define on per-buffer setup or per-custom variable basis some extra yaml header
It occured to me that the elisp coding convention were not respected in the first place. So between the 0.1.2 and 0.1.3 version, the names and variables were updated to respect them. Now every command and variables uses `org2jekyll-` and no longer `org2jekyll/` prefix.
Let org2jekyll export your org-mode file to jekyll.
What’s the difference with org-jekyll?
You don’t need to add some alien yaml in your org-mode file. You add specific org-mode headers and this will be used to format the jekyll post.
What’s the difference with happyblogger?
Only emacs’ dependencies (org, etc…) no external ruby script.
- org-mode rocks
- Github uses Jekyll
- Jekyll is nice
- Existing solutions regarding org-mode and jekyll need the org-mode files to be altered with non-org notations to work together
- I don’t want to alter my org-mode files with alien yaml headers to satisfy jekyll
Enters org2jekyll.
You have:
- your *org-publish* setup ready (mine for example)
- a running jekyll installation
Available only on marmalade for the moment. Update your packages archive with marmalade:
(require 'package)
(add-to-list 'package-archives '("marmalade" . "https://marmalade-repo.org/packages") t)
(package-initialize)M-x package-install RET org2jekyll RET
M-x customize-group RET org2jekyll RET
Here is an example of my configuration for my blog site:
(require 'org)
(require 'org2jekyll)
(custom-set-variables '(org2jekyll-blog-author "ardumont")
'(org2jekyll-source-directory (expand-file-name "~/org/"))
'(org2jekyll-jekyll-directory (expand-file-name "~/public_html/"))
'(org2jekyll-jekyll-drafts-dir "")
'(org2jekyll-jekyll-posts-dir "_posts/")
'(org-publish-project-alist
`(("default"
:base-directory ,(org2jekyll-input-directory)
:base-extension "org"
:publishing-directory ,(org2jekyll-output-directory)
:publishing-function org-html-publish-to-html
:headline-levels 4
:section-numbers nil
:with-toc nil
:html-head "<link rel=\"stylesheet\" href=\"./css/style.css\" type=\"text/css\"/>"
:html-preamble t
:recursive t
:make-index t
:html-extension "html"
:body-only t)
("post"
:base-directory ,(org2jekyll-input-directory)
:base-extension "org"
:publishing-directory ,(org2jekyll-output-directory org2jekyll-jekyll-posts-dir)
:publishing-function org-html-publish-to-html
:headline-levels 4
:section-numbers nil
:with-toc nil
:html-head "<link rel=\"stylesheet\" href=\"./css/style.css\" type=\"text/css\"/>"
:html-preamble t
:recursive t
:make-index t
:html-extension "html"
:body-only t)
("images"
:base-directory ,(org2jekyll-input-directory "img")
:base-extension "jpg\\|gif\\|png"
:publishing-directory ,(org2jekyll-output-directory "img")
:publishing-function org-publish-attachment
:recursive t)
("js"
:base-directory ,(org2jekyll-input-directory "js")
:base-extension "js"
:publishing-directory ,(org2jekyll-output-directory "js")
:publishing-function org-publish-attachment
:recursive t)
("css"
:base-directory ,(org2jekyll-input-directory "css")
:base-extension "css\\|el"
:publishing-directory ,(org2jekyll-output-directory "css")
:publishing-function org-publish-attachment
:recursive t)
("web" :components ("images" "js" "css")))))source: https://github.com/ardumont/blog-pack/blob/master/blog-pack.el#L13-L71
The previous sample contains important information:
- default and post represent the possible jekyll layouts you can use in your org2jekyll buffer `#+LAYOUT: default|post` (do not name those differently)
- images, js, css represent where you choose to store those kinds of files (you can name these as you wish)
- web is a composition of web files you may need to create a full post or page, typically, css, images, html, js, etc… (do not name this one differently either)
- blog: http://ardumont.github.io/
- jekyll exported source: https://github.com/ardumont/ardumont.github.io
- the org files: https://github.com/ardumont/org.git
Note Yes, I may have to merge the last 2 repositories at some point…
For a post (layout ‘post’) or page (layout ‘default’), add org headers (layout, title, author, date, description, categories) to your org files.
For a post (layout ‘post’):
#+STARTUP: showall
#+STARTUP: hidestars
#+OPTIONS: H:2 num:nil tags:nil toc:nil timestamps:t
#+LAYOUT: post
#+AUTHOR: ardumont
#+DATE: 2014-12-19 Fri 23:49
#+TITLE: hello
#+DESCRIPTION: some description
#+CATEGORIES: category0, category1
Note To easily do that, M-x org2jekyll-create-draft, this will ask you for everything needed and create a file with such metadata.
Now write your article in org-mode.
When ready, M-x org2jekyll-publish to publish it.
This will be published as post article.
- The #+LAYOUT entry refers to the post entry in org-publish-project-alist.
- This will create another temporary org-mode file based on the current one with the right naming convention, transform the org headers into yaml, publish to the jekyll directory (according to your org-publish setup) and delete the temporary file.
As in issue ardumont#36, you could need to add some extra jekyll headers.
Simply add them as org properties (thanks @halcyon for his work on #41).
For example, adding those properties in the org file:
#+THEME: blah
#+PLUGIN: lightense
#+SCHEME-HOVER: "#ff00b4"
Then publishing, will generate:
---
...
theme: blah
plugin: lightense
scheme-hover: "#ff00b4"
---For a page (layout ‘default’).
#+STARTUP: showall
#+STARTUP: hidestars
#+OPTIONS: H:2 num:nil tags:nil toc:nil timestamps:t
#+LAYOUT: default
#+AUTHOR: ardumont
#+DATE: 2014-12-19 Fri 23:49
#+TITLE: hello
#+DESCRIPTION: some description
#+CATEGORIES: some-category
Note To easily do that, M-x org2jekyll-create-draft, this will ask you for everything needed and create a file with such metadata.
Now create your article and publish it when ready M-x org2jekyll-publish.
Write your page. When ready, M-x org2jekyll-publish to publish it.
- The #+LAYOUT entry refers to the default entry in org-publish-project-alist.
- This will update the current org-mode with the necessary yaml and publish to the jekyll directory (according to your org-publish setup), then revert back to your normal org-mode file.
M-x org2jekyll-publish-posts
Depending on your org-publish configuration and org2jekyll, this will compile the list of org-mode posts (#+LAYOUT with ‘post’ value) and publish them.
M-x org2jekyll-publish-pages
Depending on your org-publish configuration and org2jekyll, this will compile the list of org-mode pages (#+LAYOUT with ‘default value) and publish them.
You can keep an org file in your blog directory without publishing it, by writing it as a plain org file without the org2jekyll headers. Once you’re ready to publish it as a post or an article, add the appropriate metadata headers and org2jekyll will now publish the file.
org2jekyll provides you a minor mode with the following default binding:
(setq org2jekyll-mode-map
(let ((map (make-sparse-keymap)))
(define-key map (kbd "C-c . n") 'org2jekyll-create-draft)
(define-key map (kbd "C-c . p") 'org2jekyll-publish-post)
(define-key map (kbd "C-c . P") 'org2jekyll-publish-posts)
(define-key map (kbd "C-c . l") 'org2jekyll-list-posts)
(define-key map (kbd "C-c . d") 'org2jekyll-list-drafts)
map))Note Respecting the default minor mode convention for binding
To (de)activate this in an org file: M-x org2jekyll-mode
As usual, you can use emacs’ power to setup your own bindings.
As a note, org2jekyll declares its dependencies but it’s possible that some are not fully respected. And then problem may arise. So if you found out a problem about it, feel free to open an issue mentioning the version of the library you are using.