Add Yasushi Shoji to the list of FSF-signed contributors
[worg.git] / blorgit.org
1 #+OPTIONS:    H:3 num:nil toc:2 \n:nil @:t ::t |:t ^:t -:t f:t *:t TeX:t LaTeX:t skip:nil d:(HIDE) tags:not-in-toc
2 #+STARTUP:    align fold nodlcheck hidestars oddeven lognotestate
3 #+SEQ_TODO:   TODO(t) INPROGRESS(i) WAITING(w@) | DONE(d) CANCELED(c@)
4 #+TAGS:       Write(w) Update(u) Fix(f) Check(c) 
5 #+TITLE:      Blorgit: Org-Mode based, git amenable, blogging engine
6 #+AUTHOR:     Eric Schulte
7 #+EMAIL:      schulte.eric at gmail dot com
8 #+LANGUAGE:   en
9 #+PRIORITIES: A C B
10 #+CATEGORY:   worg
11
12 # This file is the default header for new Org files in Worg.  Feel free
13 # to tailor it to your needs.
14
15 [[file:index.org][{Back to Worg's index}]]
16
17 * Introduction
18
19 Blorgit is a blogging engine which uses [[http://orgmode.org][Org-Mode]] for markup, runs on
20 the [[http://www.sinatrarb.com/][Sinatra]] mini web framework, and is amenable to posting and
21 maintenance through [[http://git-scm.com/][git]].  With the addition of a little [[http://www.ruby-lang.org/en/][Ruby]] blorgit
22 creates interactive web pages with [[http://orgmode.org][Org-Mode]].
23
24 ** Features
25
26 [[file:images/blorgit/blorgit_features.png]]
27
28 1) *In Browser Editing* Org-mode files can be edited through the
29      browser.  Upon submitting an edit the original org-mode file is
30      overwritten and the web-page is re-exported.  Edits can be turned
31      on off or with the =editable= [[* Changing Configuration Options][configuration option]] and can be
32      password protected by setting the =auth= [[* Changing Configuration Options][configuration option]]
33 2) *Export to org-mode and LaTeX formats*  The raw *Org-mode* source,
34      and *LaTeX* exports of all pages can be downloaded.
35 3) *Search* The search bar compares your search terms as a
36    /perl-style/ regular expression (in most cases working just like a
37    simple term search) against the org-mode source of each page
38    returning a ranked list.  [[file:images/blorgit/blorgit_search.png]]
39 4) *Sidebar with Recent changes and Directory Listing* The top =N=
40      recently edited pages, and/or directory listings can optionally
41      be presented in a sidebar.  These are controlled through the
42      =recent= and =dir_list= configuration options.
43 5) *Themes* The [[http://github.com/eschulte/blorgit_themes/tree/master][blorgit\_themes]] git repository holds prepackaged
44    themes for blorgit.  These can be applied to your installation
45    using the supplied rake commands.  For a list of available themes
46    run =rake themes= from the root of your blorgit installation.
47    Please share any new themes you might
48    create. [[file:images/blorgit/themes.png]]
49 6) *Comments in org-mode files* Pages can optionally be opened for
50    comments, all comments will be stored in a special =* COMMENT
51    Comments= outline header appended to the end of the org file.
52 7) *Git Synchronization* By setting the =git_commit= [[* Changing Configuration Options][configuration
53    option]] to =true= blorgit can be made to automatically commit and
54    push to a git repository after every comment or edit of an org-mode
55    file.
56
57
58 * Getting Started (installation and use)
59
60 0) *Install Ruby*
61
62    If you don't already have ruby installed on your system then you
63    will need to install [[http://www.ruby-lang.org/en/][Ruby]] and [[http://rubygems.org/][Ruby Gems]] (Ruby's package managment
64    system).*  Be sure to install Ruby 1.8 (should be default option)
65    *not* Ruby 1.9.
66
67 1) *Install the Required Gems*
68
69    #+begin_src sh
70    sudo gem install rake sinatra haml sass activesupport
71    #+end_src
72
73 2) *Install blorgit*
74
75    #+begin_src sh 
76    git clone git://github.com/eschulte/blorgit.git
77    #+end_src
78
79    Update the submodules of blorgit to provide file based persistence
80    ([[http://github.com/eschulte/active_file/tree/master][active\_file]]), org-mode interaction ([[http://github.com/eschulte/acts_as_org/tree/master][acts\_as\_org]]), and themes
81    ([[http://github.com/eschulte/blorgit_themes/tree/master][blorgit\_themes]]).
82
83    #+begin_src sh 
84    cd blorgit
85    git submodule init
86    git submodule update
87    #+end_src
88
89 3) *Create Blogs Directory*
90
91    Create a blogs directory (in =~/blogs/=) with the default
92    configuration (To change the location of the blogs directory edit
93    =blorgit.yml= in this directory).  Apply the default minimal theme
94    (for a list of available themes run =rake themes=). The Emacs Server
95    must have been started at least once as described under point 5.
96
97    #+begin_src sh 
98    rake new
99    rake themes:default
100    #+end_src
101
102 4) *Start Servers*
103   - *Emacs Server*
104
105     Starting your emacs server allows Emacs to act as a server which
106     can then export org-mode file to html.  To do this we simply need
107     to load the =org-interaction.el= file in =acts_as_org=.  You can
108     do this by executing the following in emacs
109
110    #+begin_src sh 
111    M-x load-file /path/to/blorgit/backend/acts_as_org/elisp/org-interaction.el
112    #+end_src
113
114     or with the following shell command
115
116    #+begin_src sh 
117    emacs -l backend/acts_as_org/elisp/org-interaction.el
118    #+end_src
119
120   - *Web Server*
121
122     Start your sinatra web server with the following command
123
124    #+begin_src sh 
125    ruby blorgit.rb
126    #+end_src
127
128 5) *View in Browser*
129
130    [[http://localhost:4567]]
131
132
133 * Additional Information
134 ** Common Tasks
135 Ruby has its own make tool called [[http://rake.rubyforge.org/][Rake]].  For a list of the blorgit
136 rake commands run =rake -T= from the root of your blorgit
137 installation.  At the time of writing the available rake tasks are...
138
139 #+begin_src sh
140 $ rake -T
141 (in /Users/eschulte/src/blorgit)
142 rake exported:delete  # delete all temporary exported files
143 rake exported:list    # list all temporary exported files
144 rake index            # drop a minimal index page into /Users/eschulte/Site...
145 rake info             # return configuration information about the current ...
146 rake new              # create a new blorgit instance
147 rake themes           # list the available themes
148 rake themes:default   # a default theme, should serve as a good starting point
149 rake themes:food      # a food theme for my recipes
150 rake themes:org       # an org-mode theme featuring the folding unicorn
151 #+end_src
152
153 ** Changing Configuration Options
154
155 The configuration is controlled through a [[http://www.yaml.org][YAML]] file located at
156 =blorgit.yml= in the base of your blorgit installation.  Configuration
157 variables can be used to control the *title*, *index page*,
158 *stylesheet*, the number of *recent entries* and *directory\_listings*
159 shown in the sidebar, automatic synchronization with a *git*
160 repository, *commentability*, *editability* and optional *password
161 protection* for posting edits, .  The default configuration is...
162
163 #<<configuration_options>>
164 #+begin_src sh 
165 --- 
166 title: Blorgit
167 index: index
168 style: stylesheet.css
169 recent: 5
170 dir_list: false
171 git_commit: false
172 commentable: true
173 editable: false
174 auth: 
175 - admin
176 - password
177 #+end_src
178
179 *** Directory Local Configuration
180 It is possible to specify configuration options for each individual
181 directories of your blorgit site.  To do so write the configuration
182 options you wish to specify to a file named =.blorgit.yml=.  These
183 options will be used when displaying files in the same directory as
184 the =.blorgit.yml= file.  This file follows the same format shown [[* Changing Configuration
185  Options][above]].
186
187 ** Git
188
189 If you're wondering where git comes in, initialize your new blogs
190 directory as a git repo, and post all future blogs, moderate comments
191 and commentability of blogs, and manage configuration through git.
192
193 #+begin_src sh 
194 cd ./blogs
195 git init
196 echo ".exported_*" > .gitignore # ignore export files created automatically by blorgit
197 git add .
198 git commit -a -m "initial commit"
199 #+end_src
200
201 ** Change blogs directory
202
203 To change the location of the blogs directory see the =blorgit.yml=
204 global configuration file in the base of your blorgit directory.
205
206 ** Deploying to a Remote Server
207
208 **** Thin web server
209 To run using the =run.ru= rackup file use a command like the following
210 (requires the =thin= gem =sudo gem install -v=1.0.0 thin=)
211
212 #+begin_src sh 
213 ./run.ru -sthin -p4567
214 #+end_src
215
216 **** Deploying behind a url prefix
217 If you don't want blorgit to sit at the top level of your webserver,
218 but would rather is exist behind a url prefix set the =url_prefix=
219 variable in the run.ru file.
220
221 **** Remote Emacs Server
222 Blorgit requires a running Emacs to handle the actual export of
223 org-mode pages to html (through the =emacsclient= command).  This
224 requires that an instance of Emacs be left running on the remote
225 server, which I be problematic.  I use [[http://www.gnu.org/software/screen/][gnu-screen]] to start and detach
226 from this Emacs instance as follows...
227
228 1) ssh into your remote server
229 2) start your screen session with the =screen= command
230 #+begin_src sh 
231 screen
232 #+end_src
233 3) cd to your blorgit directory
234 #+begin_src sh 
235 cd ~/src/blorgit
236 #+end_src
237 4) start emacs loading the =org-interaction.el= file
238 #+begin_src sh 
239 emacs -l backend/acts_as_org/elisp/org-interaction.el
240 #+end_src
241 5) optionally run your webserver through screen as well by 
242    1) switching to a new screen window with =\C-a c=
243    2) start your webserver
244 #+begin_src sh 
245 ./run.ru -sthin
246 #+end_src
247 6) disconnect form screen leaving emacs and the webserver running with
248    =\C-a d=
249 7) logoff from the server
250 8) at any later date you can log back into the server and reattach to
251    the original screen session with
252 #+begin_src sh 
253 screen -r
254 #+end_src
255
256 ** Extending Blorgit
257 Simplicity and a small hackable code base were key goals in the
258 construction of blorgit.  The =blorgit.rb= file in the base of the
259 application contains all of the logic and html.  Any extensions should
260 be possible through modification of this single file.  For information
261 on the structure of this file, or on the framework on which it is run
262 see [[http://www.sinatrarb.com/][Sinatra]].
263 ** Deploying on a Mac with Apache/Passenger Pane
264 A handy tool for hosting local sites on Mac OSX is the
265 [[http://www.fngtps.com/2008/06/putting-the-pane-back-into-deployment][Apache/Passenger Pane]].  This allows the setup and running of local
266 ruby web applications through a System Preferences Pane, and can be
267 used with blorgit.
268
269 1) First follow the installation instructions from [[http://www.fngtps.com/2008/06/putting-the-pane-back-into-deployment][putting-the-pane-back-into-deployment]].
270 2) clone blorgit to your =~/Sites= directory
271    #+begin_src sh
272    cd ~/Sites
273    git clone git://github.com/eschulte/blorgit.git
274    cd blorgit
275    git submodule init
276    git submodule update
277    #+end_src
278 3) Create a public and tmp directory, and copy =run.ru= to =config.ru=
279    to trick [[http://www.modrails.com/][Passenger]] into thinking blorgit is a [[http://rubyonrails.org/][rails]] application.
280    #+begin_src sh
281    mkdir public
282    mkdir tmp
283    cp run.ru config.ru
284    #+end_src
285 4) rename the blorgit directory to the name of your local site (in my
286    case "foods")
287    #+begin_src sh
288    cd ~/Sites
289    mv blorgit foods
290    #+end_src
291 5) Configure blorgit as you would normally  (see [[* Getting Started (installation and use)][Getting Started (installation and use)]])
292 6) Add your new blorgit site to Passenger Pane. [[file:images/blorgit/Passenger.png]]
293 7) Restart Apache
294    #+begin_src sh
295    sudo apachectl restart
296    #+end_src
297 8) Point your browser at the url displayed in the Passenger Pane. [[file:images/blorgit/foods.png]]