jekyll-org-mode-converter 0.1.1 → 0.1.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- 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"]
|