jekyll-org-mode-converter 0.1.1 → 0.1.4
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.org +106 -13
- data/VERSION +1 -1
- data/jekyll-org-mode-converter.gemspec +2 -2
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA1:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 5114537bb22b2d40b36abe85ce98a0678f9c7e08
|
|
4
|
+
data.tar.gz: c6088ea9b2d9684adfc039afd9eb20d342d1890d
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: 918dc42cd09ae6192bbd969cef066eeb89a54b3414fa36897473e4619509930ecb0b460d404d968042f089d829ce8972357e73085ed47f8690164083061a6c11
|
|
7
|
+
data.tar.gz: 6160688f64e0a3230ef6f2ba37b936bcd2fa2b2949b165693abe0dbd657b14554f0ba7a0d37f5c45e1825f15d0555e83b29f23121f93920bc712e7916146badf
|
data/README.org
CHANGED
|
@@ -1,25 +1,118 @@
|
|
|
1
|
-
* jekyll-org-mode-converter
|
|
2
|
-
|
|
1
|
+
* jekyll-org-mode-converter :TOC:
|
|
2
|
+
- [[#motivation][Motivation]]
|
|
3
|
+
- [[#other-solutions][Other solutions]]
|
|
4
|
+
- [[#my-approach][My approach]]
|
|
5
|
+
- [[#how-to-use-the-converter][How to use the converter]]
|
|
6
|
+
- [[#deploying-to-github][Deploying to Github]]
|
|
7
|
+
- [[#example][Example]]
|
|
8
|
+
- [[#contributing-to-jekyll-org-mode-converter][Contributing to jekyll-org-mode-converter]]
|
|
9
|
+
- [[#copyright][Copyright]]
|
|
3
10
|
|
|
4
|
-
|
|
11
|
+
** Motivation
|
|
12
|
+
I love Emacs *[[http://orgmode.org/][Org mode]]* and I try to write all my documents in Org mode and export them everywhere. Unfortunately Org mode's default html output is rather plain.
|
|
13
|
+
Enter *[[http://jekyllrb.com/][Jekyll]]*. Jekyll makes deploying static websites fun and pretty.
|
|
5
14
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
Not *every problem* is best solved by hacking Elisp.
|
|
15
|
+
** Other solutions
|
|
16
|
+
I searched for a solution to merge these two technologies and found [[https://github.com/eggcaker/jekyll-org][jekyll-org]]
|
|
17
|
+
While this seems like a great project, it has some problems:
|
|
18
|
+
- It is not compatible with recent versions of Org mode
|
|
19
|
+
- The workflow seems pretty complex.
|
|
12
20
|
|
|
13
|
-
|
|
14
|
-
org-to-html converter called [[https://github.com/bdewey/org-ruby][org-ruby]]. Org-ruby is what Github uses to render this org-mode README file to html.
|
|
21
|
+
To convert your documents you need to run a separate make file that runs some elisp to convert your org files to html, and then run Jekyll in a sub directory on the converted html to build the resulting website.
|
|
15
22
|
|
|
16
|
-
|
|
23
|
+
While I understand that hacking Elisp seems like the appropriate course of action for the experienced Emacs user in any scenario,
|
|
24
|
+
I don't believe *every problem* is best solved by hacking Elisp.
|
|
17
25
|
|
|
26
|
+
** My approach
|
|
27
|
+
I decided to approach the problem from a Jekyll point of view. I wanted to use the standard Jekyll workflow, only with Org mode files instead of Markdown files.
|
|
28
|
+
|
|
29
|
+
Luckily Jekyll makes it easy to write a [[http://jekyllrb.com/docs/plugins/#converters][converter]] for a new markup language. To make the job even easier there already exists a ruby based
|
|
30
|
+
org-to-html converter [[https://github.com/bdewey/org-ruby][org-ruby]]. Org-ruby is what Github uses to render Org mode files (like this README) to html.
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
** How to use the converter
|
|
34
|
+
*** Short version
|
|
35
|
+
For experienced Jekyll users, you need to do 2 things to get ~jekyll-org-mode-converter~ to work
|
|
36
|
+
- Install the gem
|
|
37
|
+
- Include the gem in your ~_config.yml~
|
|
38
|
+
|
|
39
|
+
*** Long version
|
|
40
|
+
To use ~jekyll-org-mode-converter~ with Jekyll, you need to have Ruby RubyGems and Jekyll installed. See how to do that [[http://jekyllrb.com/docs/installation/][here]].
|
|
41
|
+
|
|
42
|
+
Create a new Jekyll project ~my-site~ run:
|
|
43
|
+
#+begin_src sh
|
|
44
|
+
jekyll new my-site
|
|
45
|
+
#+end_src
|
|
46
|
+
|
|
47
|
+
Create a Gemfile in the root of the project, and add at least the following lines:
|
|
48
|
+
#+begin_src ruby
|
|
49
|
+
source 'https://rubygems.org'
|
|
50
|
+
|
|
51
|
+
gem 'jekyll' , '>= 2.5.3'
|
|
52
|
+
gem 'jekyll-org-mode-converter' , '>= 0.1.1'
|
|
53
|
+
#+end_src
|
|
54
|
+
|
|
55
|
+
Install the gems with bundler:
|
|
56
|
+
#+begin_src sh
|
|
57
|
+
bundle install
|
|
58
|
+
#+end_src
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
To use the new converter add the following line to your ~_config.yml~:
|
|
18
62
|
#+begin_src ruby
|
|
19
63
|
gems: [jekyll-org-mode-converter]
|
|
20
64
|
#+end_src
|
|
21
65
|
|
|
22
|
-
Now
|
|
66
|
+
Now write your jekyll posts in Org mode!
|
|
67
|
+
|
|
68
|
+
To build your site run:
|
|
69
|
+
#+begin_src sh
|
|
70
|
+
bundle exec jekyll build
|
|
71
|
+
#+end_src
|
|
72
|
+
|
|
73
|
+
and to serve your site run:
|
|
74
|
+
#+begin_src sh
|
|
75
|
+
bundle exec jekyll serve
|
|
76
|
+
#+end_src
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
** Deploying to Github
|
|
80
|
+
One of the cool features of Jekyll is that you can deploy Jekyll websites to Github by simply pushing the Jekyll code
|
|
81
|
+
to your GitHub remote. Unfortunately for us Github does not allow you to run custom plugins for [[http://jekyllrb.com/docs/plugins/][security reasons]].
|
|
82
|
+
This implies that to use [[https://help.github.com/articles/using-jekyll-with-pages/][Jekyll with GitHub Pages]] you ideally need to write posts in Markdown. But I love Org mode and I don't want to learn yet another markup language.
|
|
83
|
+
|
|
84
|
+
Luckily all is not lost, but you will need to build your site locally and push your static pages to GitHub.
|
|
85
|
+
To keep everything tidy I organize my git repository in the following way
|
|
86
|
+
|
|
87
|
+
#+begin_src
|
|
88
|
+
.
|
|
89
|
+
|
|
|
90
|
+
|-- src (the root of my jekyll project)
|
|
91
|
+
|
|
|
92
|
+
|-- www (resulting site goes here)
|
|
93
|
+
|
|
|
94
|
+
|-- index.html (redirects to www/index.html)
|
|
95
|
+
#+end_src
|
|
96
|
+
|
|
97
|
+
|
|
98
|
+
You will need to configure the custom destination directory by adding the following line in your ~_config.yml~
|
|
99
|
+
#+begin_src ruby
|
|
100
|
+
destination: ../www
|
|
101
|
+
#+end_src
|
|
102
|
+
|
|
103
|
+
Create ~index.html~ with the following content
|
|
104
|
+
#+begin_src html
|
|
105
|
+
<html>
|
|
106
|
+
<meta http-equiv="refresh" content="0; url=www" />
|
|
107
|
+
</html>
|
|
108
|
+
#+end_src
|
|
109
|
+
|
|
110
|
+
Run ~jekyll build~ on the ~src~ directory and push the results to GitHub.
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
|
|
114
|
+
** Example
|
|
115
|
+
I run my personal website on Github using the technique described above. You can look at the code [[http://tjaartvdwalt.github.io/][here]].
|
|
23
116
|
|
|
24
117
|
** Contributing to jekyll-org-mode-converter
|
|
25
118
|
|
data/VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
0.1.
|
|
1
|
+
0.1.4
|
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
# DO NOT EDIT THIS FILE DIRECTLY
|
|
3
3
|
# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
|
|
4
4
|
# -*- encoding: utf-8 -*-
|
|
5
|
-
# stub: jekyll-org-mode-converter 0.1.
|
|
5
|
+
# stub: jekyll-org-mode-converter 0.1.4 ruby lib
|
|
6
6
|
|
|
7
7
|
Gem::Specification.new do |s|
|
|
8
8
|
s.name = "jekyll-org-mode-converter"
|
|
9
|
-
s.version = "0.1.
|
|
9
|
+
s.version = "0.1.4"
|
|
10
10
|
|
|
11
11
|
s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
|
|
12
12
|
s.require_paths = ["lib"]
|