shinmun 0.2 → 0.5

Sign up to get free protection for your applications and to get access to all the features.
data/README.md CHANGED
@@ -1,218 +1,149 @@
1
- Shinmun, a small and beautiful blog engine
2
- ==========================================
1
+ Shinmun - a git-based blog engine
2
+ =================================
3
3
 
4
- Shinmun is a **minimalist blog engine**. You just write posts as text files,
5
- render them to static files and push your blog to your server.
4
+ Shinmun is a small git-based blog engine. Write posts in your favorite
5
+ editor, git-push it and serve your blog straight from a repository.
6
6
 
7
- This allows you to write posts in your favorite editor like Emacs or
8
- VI and use a VCS like git.
7
+ ### Features
9
8
 
10
- Your layout can be customized by a set of *ERB templates*. These
11
- templates have access to `Post` objects and *helper methods* so that
12
- anybody who knows *Rails* should feel comfortable with it.
13
-
14
-
15
- ### Shinmun Features
16
-
17
- * Index listing
18
- * Category listing
19
- * Archive listings for each month
20
- * RSS feeds for index and category pages
21
- * Builtin webserver for realtime rendering
22
- * Compression of javascript files with PackR
23
- * Included syntax highlighting through `highlight.js`
24
- * AJAX comment system with PHP JSON file storage
25
- * Integration of WMD-Markdown Editor for commenting
9
+ * Posts are text files formatted with [Markdown][8], [Textile][9] or [HTML][10]
10
+ * Runs on [Rack][6], [Kontrol][3] and [GitStore][7]
11
+ * Deploy via [git-push][11]
12
+ * Index, category and archive listings
13
+ * RSS feeds
14
+ * Syntax highlighting provided by [CodeRay][4]
15
+ * Markdown comments
26
16
 
27
17
 
28
18
  ### Quickstart
29
19
 
30
- Install the gem:
31
-
32
- gem install shinmun
20
+ Install the gems:
33
21
 
34
- Download and extract the example blog from my [github repository][3].
22
+ $ gem sources -a http://gems.github.com
23
+ $ gem install rack BlueCloth rubypants coderay georgi-git_store georgi-kontrol georgi-shinmun
35
24
 
36
- Issue the following commands and you will see the blog on
37
- `http://localhost:3000`:
25
+ Create a sample blog:
38
26
 
39
- cd shinmun-example
40
- shinmun server
27
+ $ shinmun init myblog
41
28
 
29
+ This will create a directory with all necessary files. Now start the
30
+ web server:
42
31
 
43
- ### Writing Posts
32
+ $ cd myblog
33
+ $ rackup
44
34
 
45
- Posts can be created by using the `shinmun` command inside your blog folder:
35
+ Browse to the following url:
46
36
 
47
- shinmun new 'The title of the post'
37
+ http://localhost:9292
48
38
 
49
- Shinmun will then create a post file in the right place, for example
50
- in `posts/2008/9/the-title-of-the-post.md`. After creating you will
51
- probably open the file, set the category and start writing your new
52
- article.
39
+ Voilà, your first blog is up and running!
53
40
 
54
- Now you want to look at your rendered post. Just run:
55
41
 
56
- shinmun server
42
+ ### Writing Posts
57
43
 
58
- Go to `http://localhost:3000` and you will see your blog served in
59
- realtime. Just change and save any of your posts and you will see the
60
- new output in your browser.
44
+ Posts can be created by using the `shinmun` command inside your blog
45
+ folder:
61
46
 
62
- After finishing your post, you may run `shinmun render` and the output
63
- will be rendered to the *public* folder.
47
+ shinmun post 'The title of the post'
64
48
 
65
- By issuing the `shinmun push` command your blog will be pushed to your
66
- server using rsync. This works only, if you define the blog_repository
67
- variable inside blog.yml. It should contain something like
68
- `user@myhost.com:/var/www/my-site/`.
49
+ Shinmun will then create a post file in the right place, for example
50
+ in `posts/2008/9/the-title-of-the-post.md` and open it with $EDITOR.
69
51
 
70
52
 
71
53
  ### Post Format
72
54
 
73
- Each blog post is just a text file with an optional header section and
74
- a markup body, which are separated by a newline. Normally you don't
75
- have to worry about the post format, if you create posts with the
76
- `shinmun new` command.
55
+ Each blog post is just a text file with a YAML header and a body. The
56
+ YAML header is surrounded with 2 lines of 3 dashes. This format is
57
+ compatible with [Jekyll][13] and [Github Pages][14].
77
58
 
78
- The **first line** of the header should start with 3 dashes as usual
79
- for a YAML document.
59
+ The YAML header has following attributes:
80
60
 
81
- The title of your post will be parsed from your first heading
82
- according to the document type. Shinmun will try to figure out the
83
- title for Markdown, Textile and HTML files.
84
-
85
- The yaml header may have following attributes:
86
-
87
- * `date`: post will show up in blog page and archive pages
88
- * `category`: post will show up in the defined category page
89
- * `guid`: will be set automatically by Shinmun
90
-
91
- Posts without a date are by definition static pages.
61
+ * `title`: mandatory
62
+ * `date`: posts need one, pages not
63
+ * `category`: a post belongs to one category
64
+ * `tags`: a comma separated list of tags
92
65
 
93
66
  Example post:
94
67
 
95
- <pre>
96
-
97
68
  ---
98
- category: Ruby
99
69
  date: 2008-09-05
100
- guid: 7ad04f10-5dd6-012b-b53c-001a92975b89
101
-
102
- BlueCloth, a Markdown library
103
- =============================
104
-
70
+ category: Ruby
71
+ tags: bluecloth, markdown
72
+ title: BlueCloth, a Markdown library
73
+ ---
105
74
  This is the summary, which is by definition the first paragraph of the
106
75
  article. The summary shows up in category listings or the index listing.
107
76
 
108
- </pre>
109
77
 
110
- The guid should never change, as it will be you used for identifying
111
- posts for comments.
78
+ ### Syntax highlighting
112
79
 
80
+ Thanks to the fantastic highlighting library [CodeRay][4], highlighted
81
+ code blocks can be embedded easily in Markdown. For Textile support
82
+ you have to require `coderay/for_redcloth`. These languages are
83
+ supported: C, Diff, Javascript, Scheme, CSS, HTML, XML, Java, JSON,
84
+ RHTML, YAML, Delphi
113
85
 
114
- ### Directory layout
115
-
116
- * Your **assets** are in the `assets` folder, which gets copied to the
117
- public folder in the render step.
118
-
119
- * The **settings of your blog** are defined in `config/blog.yml`
120
-
121
- * Your **posts** reside in the `posts` folder sorted by year/month.
86
+ To activate CodeRay for a code block, you have to declare the language
87
+ in lower case:
122
88
 
123
- * Your **pages** are located in the `pages` folder.
89
+ @@ruby
124
90
 
125
- * **Template** files are in the `templates` folder.
91
+ def method_missing(id, *args, &block)
92
+ puts "#{id} was called with #{args.inspect}"
93
+ end
126
94
 
127
- * The **index page** of your blog is defined in `pages/index.rhtml` and
128
- may be customized.
95
+ **Note that the declaration MUST be followed by a blank line!**
129
96
 
130
- * **Archive pages** will be rendered to files like `public/2008/9/index.html`.
131
97
 
132
- * **Category pages** will be rendered to files like `public/categories/ruby.html`.
133
-
134
-
135
- An example tree:
98
+ ### Directory layout
136
99
 
137
100
  + assets
138
- + images
139
- + stylesheets
140
- + javascripts
141
- + config
142
- + blog.yml
101
+ + print.css
102
+ + styles.css
103
+ + config.ru
143
104
  + pages
144
105
  + about.md
145
- + index.rhtml
146
106
  + posts
147
107
  + 2007
148
108
  + 2008
149
109
  + 9
150
110
  + my-article.md
151
111
  + templates
152
- + feed.rxml
112
+ + 404.rhtml
113
+ + archive.rhtml
114
+ + category.rhtml
115
+ + category.rxml
116
+ + _comments.rhtml
117
+ + _comment_form.rhtml
118
+ + index.rhtml
119
+ + index.rxml
120
+ + index.rhtml
153
121
  + layout.rhtml
154
- + page.rhtml
122
+ + page.rhtml
155
123
  + post.rhtml
156
- + posts.rhtml
157
-
158
-
159
- The output will look like this:
160
-
161
- + public
162
- + index.html
163
- + about.html
164
- + categories
165
- + emacs.html
166
- + ruby.html
167
- + 2007
168
- + 2008
169
- + 9
170
- + my-article.html
171
- + images
172
- + stylesheets
173
- + javascripts
174
124
 
125
+ ### Blog configuation
175
126
 
176
- ### Config file
127
+ In `config.ru` you can set the properties of your blog:
177
128
 
178
- The configuration of the blog system consists of some variables
179
- encoded as yaml file:
129
+ blog.config = {
130
+ :language => 'en',
131
+ :title => "Blog Title",
132
+ :author => "The Author",
133
+ :categories => ["Ruby", "Javascript"],
134
+ :description => "Blog description"
135
+ }
180
136
 
181
- * blog_title: the title of your blog, used for rss
182
137
 
183
- * blog_description: used for rss
184
-
185
- * blog_language: used for rss
186
-
187
- * blog_author: used for rss, acts also as fallback for the blog.author variable
188
-
189
- * blog_url: used for rss
190
-
191
- * blog_repository: path for rsync, used for `shinmun push` command
192
-
193
- * base_path: if your blog should not be rendered to your site
194
- root, you can define a sub path here (like `blog`)
195
-
196
- * images_path: used for templates helper, defaults to `images`
197
-
198
- * javascripts_path: used for templates helper, defaults to `javascripts`
199
-
200
- * stylesheets_path: used for templates helper, defaults to `stylesheets`
201
-
202
- * pack_javascripts: a list of scripts to be compressed
203
-
204
- * pack_stylesheets: a list of stylesheets to be concatenated
205
-
206
-
207
- ### Layout
138
+ ### Templates
208
139
 
209
140
  Layout and templates are rendered by *ERB*. The layout is defined in
210
- `layout.rhtml`. The content will be provided in the variable
141
+ `templates/layout.rhtml`. The content will be provided in the variable
211
142
  `@content`. A minimal example:
212
143
 
213
144
  <html>
214
145
  <head>
215
- <title><%= @blog_title %></title>
146
+ <title><%= @blog.title %></title>
216
147
  <%= stylesheet_link_tag 'style' %>
217
148
  </head>
218
149
  <body>
@@ -220,95 +151,99 @@ Layout and templates are rendered by *ERB*. The layout is defined in
220
151
  </body>
221
152
  </html>
222
153
 
154
+ The attributes of a post are accessible via the @post variable:
223
155
 
224
- ### Helpers
225
-
226
- There are also helper methods, which work the same way like the *Rails*
227
- helpers. The most important ones are these:
228
-
229
- * `stylesheet_link_tag(*names)` links a stylesheet with a timestamp
230
-
231
- * `javascript_tag(*names)` includes a javascript with a timestamp
232
-
233
- * `image_tag(src, options = {})` renders an image tag
156
+ <div class="article">
157
+
158
+ <h1><%= @post.title %></h1>
159
+
160
+ <div class="date">
161
+ <%= human_date @post.date %>
162
+ </div>
163
+
164
+ <%= @post.body_html %>
234
165
 
235
- * `link_to(text, path, options = {})` renders a link
166
+ ...
236
167
 
237
- Stylesheets, javascripts and images should be included by using theses
238
- helpers. The helper methods will include a timestamp of the
239
- modification time as `querystring`, so that the browser will fetch the
240
- new resource if it has been changed.
168
+ </div>
241
169
 
242
- If you want to define your own helpers, just define a file named
243
- `templates/helpers.rb` with a module named `Shinmun::Helpers`. This
244
- module will be included into the `Shinmun::Template` class.
245
170
 
171
+ ### Commenting System
246
172
 
247
- ### Post Template
173
+ Comments are stored as flat files and encoded as YAML objects. Each
174
+ post has a corresponding comment file located at `comments/<path to
175
+ post>`. So administration of comments is possible by editing the YAML
176
+ file, which can be done on your local machine, as you can just pull
177
+ the comments from your live server.
248
178
 
249
- The attributes of a post are accessible as instance variables in a template:
250
179
 
251
- <div class="article">
180
+ ### Deployment
252
181
 
253
- <div class="date">
254
- <%= date @date %>
255
- </div>
256
-
257
- <h2><%= @title %></h2>
258
-
259
- <%= @body %>
260
-
261
- <h3>Comments</h3>
182
+ Shinmun can server the blog straight from the git repository. So on
183
+ your webserver initialize a new git repo like:
262
184
 
263
- <!-- Here you may put my commenting system -->
264
- </div>
185
+ $ cd /var/www
186
+ $ mkdir myblog
187
+ $ cd myblog
188
+ $ git init
265
189
 
190
+ Now on your local machine, you add a new remote repository and push
191
+ your blog to your server:
266
192
 
267
- ### RSS Feeds
193
+ $ cd ~/myblog
194
+ $ git remote add live ssh://myserver.com/var/www/myblog
195
+ $ git push live
268
196
 
269
- Feeds will be rendered by the *ERB template*
270
- `templates/feed.rxml`. Some of the variables have been read from the
271
- `blog.yml`, like `@blog_title`, other variables have been determined
272
- by the engine like `@posts` or `@category`.
273
197
 
198
+ On your production server, you just need the rackup file `config.ru`
199
+ to run the blog:
274
200
 
275
- ### Packr Support
201
+ $ git checkout config.ru
276
202
 
277
- If you set the variables `pack_javascripts` or `pack_stylesheets`,
278
- Shinmun will create the files `all.js` or `all.css` automatically
279
- on rendering (even on each request of the webserver).
203
+ Now you can run just a pure ruby server or something like Phusion
204
+ Passenger. Anytime you want to publish a post on your blog, you
205
+ just write, commit and finally push a post by:
280
206
 
281
- The Javascript will be compressed with Packr and for performance
282
- reasons, minified versions for each of your javascripts will be
283
- created automatically in `assets/javascripts`.
207
+ $ git commit -a -m 'new post'
208
+ $ git push live
284
209
 
285
- The stylesheets will be just concatenated to one file named `all.css`.
286
210
 
287
- Note that you define a yaml array of filenames without file
288
- extensions, so it should like `[jquery, jquery-form]`.
211
+ ### Phusion Passenger
289
212
 
213
+ Shinmun is compatible with [Phusion Passenger][5]. Install Phusion
214
+ Passenger as described in my [blog post][2].
290
215
 
291
- ### Commenting System
216
+ Assuming that you are on a Debian or Ubuntu system, you can create a
217
+ file named `/etc/apache2/sites-available/blog`:
292
218
 
293
- As I am not willing to build up a whole Rails stack for a single blog,
294
- I was looking for a simple storage for comments. I really like the
295
- JSON format. It works seamlessly with Javascript libraries and can be
296
- serialized and deserialized from almost any language.
219
+ <VirtualHost *:80>
220
+ ServerName myblog.com
221
+ DocumentRoot /var/www/blog/public
222
+ </VirtualHost>
297
223
 
298
- Read about my [lightweight commenting system][2].
224
+ Enable the new virtual host:
299
225
 
226
+ $ a2ensite myapp
300
227
 
301
- ### Download
228
+ After restarting Apache your blog should run on Apache on your desired
229
+ domain:
302
230
 
303
- Simply install the gem:
231
+ $ /etc/init.d/apache2 restart
304
232
 
305
- gem install shinmun
306
233
 
234
+ ### GitHub Project
307
235
 
308
236
  Download or fork the package at my [github repository][1]
309
237
 
310
238
 
311
-
312
- [1]: http://github.com/georgi/shinmun/tree/master
313
- [2]: commenting-system-with-lightweight-json-store.html
314
- [3]: http://github.com/georgi/shinmun-example/tree/master
239
+ [1]: http://github.com/georgi/shinmun
240
+ [2]: http://www.matthias-georgi.de/2008/9/quick-guide-for-passenger-on-ubuntu-hardy.html
241
+ [3]: http://github.com/georgi/kontrol
242
+ [4]: http://coderay.rubychan.de/
243
+ [5]: http://www.modrails.com/
244
+ [6]: http://github.com/rack/rack
245
+ [7]: http://github.com/georgi/git_store
246
+ [8]: http://daringfireball.net/projects/markdown/
247
+ [9]: http://textile.thresholdstate.com/
248
+ [10]: http://en.wikipedia.org/wiki/Html
249
+ [11]: http://www.kernel.org/pub/software/scm/git/docs/git-push.html
data/Rakefile CHANGED
@@ -1,51 +1,32 @@
1
- require 'rubygems'
2
-
3
1
  require 'rake'
4
- require 'rake/clean'
5
2
  require 'rake/rdoctask'
6
- require 'rake/packagetask'
7
- require 'rake/gempackagetask'
8
- require 'fileutils'
9
3
 
10
- spec = Gem::Specification.new do |s|
11
- s.name = "shinmun"
12
- s.version = `git describe`
13
- s.platform = Gem::Platform::RUBY
14
- s.summary = "a small blog engine"
15
-
16
- s.description = <<-EOF
17
- Shinmun is a blog engine, which renders text files using a markup
18
- language like Markdown and a set of templates into either static web
19
- pages or serving them over a rack adapter. Shinmun supports
20
- categories, archives, rss feeds and commenting.
21
- EOF
22
-
23
- s.files = `git ls-files`.split("\n").reject { |f| f.match /^pkg/ }
24
- s.bindir = 'bin'
25
- s.executables << 'shinmun'
26
- s.require_path = 'lib'
27
- s.add_dependency 'BlueCloth'
28
- s.add_dependency 'rubypants'
29
- s.has_rdoc = true
30
- s.extra_rdoc_files = ['README.md']
31
-
32
- s.author = 'Matthias Georgi'
33
- s.email = 'matti.georgi@gmail.com'
34
- s.homepage = 'http://shinmun.rubyforge.org'
35
- s.rubyforge_project = 'shinmun'
4
+ begin
5
+ require 'spec/rake/spectask'
6
+ rescue LoadError
7
+ puts <<-EOS
8
+ To use rspec for testing you must install the rspec gem:
9
+ gem install rspec
10
+ EOS
11
+ exit(0)
12
+ end
13
+
14
+ desc "Run all specs"
15
+ Spec::Rake::SpecTask.new(:spec) do |t|
16
+ t.spec_opts = ['-cfs']
17
+ t.spec_files = FileList['test/**/*_spec.rb']
36
18
  end
37
19
 
38
- Rake::GemPackageTask.new(spec) do |p|
39
- p.gem_spec = spec
40
- p.need_tar = false
41
- p.need_zip = false
20
+ desc "Print SpecDocs"
21
+ Spec::Rake::SpecTask.new(:doc) do |t|
22
+ t.spec_opts = ["--format", "specdoc"]
23
+ t.spec_files = FileList['test/*_spec.rb']
42
24
  end
43
25
 
44
-
45
26
  desc "Generate RDoc documentation"
46
27
  Rake::RDocTask.new(:rdoc) do |rdoc|
47
28
  rdoc.options << '--line-numbers' << '--inline-source' <<
48
- '--main' << 'README' <<
29
+ '--main' << 'README.md' <<
49
30
  '--title' << 'Shinmun Documentation' <<
50
31
  '--charset' << 'utf-8'
51
32
  rdoc.rdoc_dir = "doc"
@@ -55,18 +36,5 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
55
36
  end
56
37
  end
57
38
 
58
-
59
- task :pdoc => [:rdoc] do
60
- sh "rsync -avz doc/ mgeorgi@rubyforge.org:/var/www/gforge-projects/shinmun"
61
- end
62
-
63
- desc "Publish the release files to RubyForge."
64
- task :release => [ :gem ] do
65
- require 'rubyforge'
66
- require 'rake/contrib/rubyforgepublisher'
67
-
68
- rubyforge = RubyForge.new
69
- rubyforge.configure
70
- rubyforge.login
71
- rubyforge.add_release('shinmun', 'shinmun', spec.version, "pkg/shinmun-#{spec.version}.gem")
72
- end
39
+ desc "Run the rspec"
40
+ task :default => :spec
data/assets/print.css ADDED
@@ -0,0 +1,76 @@
1
+ body {
2
+ line-height:1.5;
3
+ font-family:"Helvetica Neue", "Lucida Grande", Arial, Verdana, sans-serif;
4
+ color:#000;
5
+ background:none;
6
+ font-size:10pt;
7
+ }
8
+
9
+ .container {
10
+ background:none;
11
+ }
12
+
13
+ h1,h2,h3,h4,h5,h6 {
14
+ font-family:"Helvetica Neue", Arial, "Lucida Grande", sans-serif;
15
+ }
16
+
17
+ code {
18
+ font:.9em "Courier New", Monaco, Courier, monospace;
19
+ }
20
+
21
+ img {
22
+ float:left;
23
+ margin:1.5em 1.5em 1.5em 0;
24
+ }
25
+
26
+ a img {
27
+ border:none;
28
+ }
29
+
30
+ p img.top {
31
+ margin-top:0;
32
+ }
33
+
34
+ hr {
35
+ background:#ccc;
36
+ color:#ccc;
37
+ width:100%;
38
+ height:2px;
39
+ border:none;
40
+ margin:2em 0;
41
+ padding:0;
42
+ }
43
+
44
+ blockquote {
45
+ font-style:italic;
46
+ font-size:.9em;
47
+ margin:1.5em;
48
+ padding:1em;
49
+ }
50
+
51
+ .small {
52
+ font-size:.9em;
53
+ }
54
+
55
+ .large {
56
+ font-size:1.1em;
57
+ }
58
+
59
+ .quiet {
60
+ color:#999;
61
+ }
62
+
63
+ .hide {
64
+ display:none;
65
+ }
66
+
67
+ a:link,a:visited {
68
+ background:transparent;
69
+ font-weight:700;
70
+ text-decoration:underline;
71
+ }
72
+
73
+ a:link:after,a:visited:after {
74
+ content:" (" attr(href) ") ";
75
+ font-size:90%;
76
+ }