Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/eggcaker/jekyll-org

org-mode converter for Jekyll.
https://github.com/eggcaker/jekyll-org

jekyll org-mode

Last synced: 3 days ago
JSON representation

org-mode converter for Jekyll.

Awesome Lists containing this project

README 

        
* jekyll-org



*Looking for a New Maintainer*

 

*Notice*: I am currently not really using ruby and jekyll right now, and I am looking for someone who is interested and willing to take over its maintenance. If you're interested, please contact me using one of the methods below:

Send an email to: [email protected]

Leave a message in the issues.



** Overview



This plugin adds [[http://orgmode.org/][Org mode]] support to [[http://jekyllrb.com][Jekyll]] and lets you write posts

and pages in Org.



** Related Projects 

   

What's the difference with org2jekll 

You don’t need to any org-publish-project-alist to starting write post, just start with any editor that org-mode supported



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?

No more external ruby script. 



** Requirements



- Jekyll

- org-ruby



** Installation

*** Short version



For experienced Jekyll users, you need to do 2 things to get

~jekyll-org~ to work :



- Include the gem in your ~_config.yml~

- Include the gem in Gemfile



*** Long version



To use ~jekyll-org~ with Jekyll, you need to have Ruby RubyGems and

Jekyll installed.  See how to do that [[http://jekyllrb.com/docs/installation/][here]].



Create a new Jekyll project ~my-site~ run:



#+begin_src sh

jekyll new my-site

#+end_src



Create a Gemfile in the root of the project, and add at least the

following lines:



#+begin_src ruby

source 'https://rubygems.org'



gem 'jekyll' , '>= 3.0.0'

gem 'jekyll-org', '>= 1.1.0'

#+end_src



Install the gems with bundler:



#+begin_src sh

bundle install

#+end_src



To use the new converter add the following line to your ~_config.yml~:



#+begin_src yml

plugins:

  - jekyll-org

#+end_src



:warning: If you are using Jekyll < 3.5.0 use the gems key instead of plugins.



** Usage



Create a new file with =.org= extension in =_posts=, and write the post

with Org. That is all! Generate your Jekyll site as you usually do.



** Front matter



Instead of YAML the front matter is configured in the usual Org way,

with no lines.   



Below is an example of an Org post, featuring front matter, tags, tables,

liquid templating and syntax highlighting. To render this example, remove

the leading hash symbols (#) at =#+begin_src= and =#+begin_end= beforehand

(this is a workaround for GitHub's org rendering).



#+BEGIN_EXAMPLE

#+TITLE: Jekyll and Org together

#+LAYOUT: post

#+TAGS: jekyll org-mode "tag with spaces"



This is a blog post about Jekyll and Org mode.



** org-table demo 



   | a | b | c | d | e |

   |---+---+---+---+---|

   | 1 | 2 | 3 | 4 | 5 |



** Liquid demo 

   #+liquid: enabled

   #+foo: hello world

   {{ page.foo }}



   or



   {{ site.time | date_to_xmlschema }}

   

** Code highlighting

   Jekyll-org also offers powerful support for code snippets:

   ##+begin_src  ruby 

     def print_hi(name)

       puts "Hi, #{name}"

     end

     print_hi('Tom')



     #=> prints 'Hi, Tom' to STDOUT.

   ##+end_src

#+END_EXAMPLE



The value of =#+TAGS= is parsed into a list by splitting it on spaces,

tags containing spaces can be wrapped into quotes.



** Liquid templating



By default the all content is exported to raw HTML with org-ruby, but

you can add =#+liquid: whatevervalue== in the header.  Then you can use

[[http://docs.shopify.com/themes/liquid-documentation/basics][Liquid]] tags.



For example, if your Org file contains



#+BEGIN_EXAMPLE

#+liquid: enabled

#+foo: hello world



{{ page.foo }}



or



{{ site.time | date_to_xmlschema }}



#+END_EXAMPLE



then you will get output like



#+BEGIN_EXAMPLE

hello world


or


2014-07-02T08:20:28+08:00


#+END_EXAMPLE



*** Site wide config



Alternatively, if you'd rather enable liquid by default for every

org file being converted, you can enable it in your /_config.yml/

file.



#+BEGIN_EXAMPLE

org:

  liquid: true

#+END_EXAMPLE



** Source code highlighting



To enable source code highlighting, run =bundle add pygments.rb=. If your Jekyll

theme has built-in support for syntax highlighting, you're all set! Otherwise, add a =pygments=-compatible

CSS file to your site's =/assets/css/= folder. You can find a bunch of CSS themes for =pygments= in

[[https://github.com/richleland/pygments-css][this repository]], or create your own (some related =pygments= documentation is [[https://pygments.org/docs/styles/][here]]).



Then, add a source code block as you would in Org, for example Ruby:



#+BEGIN_EXAMPLE

#+BEGIN_SRC

 require 'rubygems'

 require 'org-ruby'

 data = IO.read(filename)

 puts Orgmode::Parser.new(data).to_html

#+END_SRC

#+END_EXAMPLE



And the output will have code highlighting:



#+BEGIN_SRC ruby

 require 'rubygems'

 require 'org-ruby'

 data = IO.read(filename)

 puts Orgmode::Parser.new(data).to_html

#+END_SRC



** Author



eggcaker 



** License



MIT