shinmun 0.2 → 0.5

data/README.md

@@ -1,218 +1,149 @@
-Shinmun, a small and beautiful blog engine
-==========================================
+Shinmun - a git-based blog engine
+=================================
 
-Shinmun is a **minimalist blog engine**. You just write posts as text files,
-render them to static files and push your blog to your server.
+Shinmun is a small git-based blog engine. Write posts in your favorite
+editor, git-push it and serve your blog straight from a repository.
 
-This allows you to write posts in your favorite editor like Emacs or
-VI and use a VCS like git.
+### Features
 
-Your layout can be customized by a set of *ERB templates*. These
-templates have access to `Post` objects and *helper methods* so that
-anybody who knows *Rails* should feel comfortable with it.
-
-
-### Shinmun Features
-
-* Index listing
-* Category listing
-* Archive listings for each month
-* RSS feeds for index and category pages
-* Builtin webserver for realtime rendering
-* Compression of javascript files with PackR
-* Included syntax highlighting through `highlight.js`
-* AJAX comment system with PHP JSON file storage
-* Integration of WMD-Markdown Editor for commenting
+* Posts are text files formatted with [Markdown][8], [Textile][9] or [HTML][10]
+* Runs on [Rack][6], [Kontrol][3] and [GitStore][7]
+* Deploy via [git-push][11]
+* Index, category and archive listings
+* RSS feeds
+* Syntax highlighting provided by [CodeRay][4]
+* Markdown comments
 
 
 ### Quickstart
 
-Install the gem:
-
-    gem install shinmun
+Install the gems:
 
-Download and extract the example blog from my [github repository][3].
+    $ gem sources -a http://gems.github.com
+    $ gem install rack BlueCloth rubypants coderay georgi-git_store georgi-kontrol georgi-shinmun
 
-Issue the following commands and you will see the blog on
-`http://localhost:3000`:
+Create a sample blog:
 
-    cd shinmun-example
-    shinmun server
+    $ shinmun init myblog
 
+This will create a directory with all necessary files. Now start the
+web server:
 
-### Writing Posts
+    $ cd myblog
+    $ rackup
 
-Posts can be created by using the `shinmun` command inside your blog folder:
+Browse to the following url:
 
-    shinmun new 'The title of the post'
+    http://localhost:9292
 
-Shinmun will then create a post file in the right place, for example
-in `posts/2008/9/the-title-of-the-post.md`. After creating you will
-probably open the file, set the category and start writing your new
-article.
+Voilà, your first blog is up and running!
 
-Now you want to look at your rendered post. Just run:
 
-    shinmun server
+### Writing Posts
 
-Go to `http://localhost:3000` and you will see your blog served in
-realtime. Just change and save any of your posts and you will see the
-new output in your browser.
+Posts can be created by using the `shinmun` command inside your blog
+folder:
 
-After finishing your post, you may run `shinmun render` and the output
-will be rendered to the *public* folder.
+    shinmun post 'The title of the post'
 
-By issuing the `shinmun push` command your blog will be pushed to your
-server using rsync. This works only, if you define the blog_repository
-variable inside blog.yml. It should contain something like
-`user@myhost.com:/var/www/my-site/`.
+Shinmun will then create a post file in the right place, for example
+in `posts/2008/9/the-title-of-the-post.md` and open it with $EDITOR.
 
 
 ### Post Format
 
-Each blog post is just a text file with an optional header section and
-a markup body, which are separated by a newline. Normally you don't
-have to worry about the post format, if you create posts with the
-`shinmun new` command.
+Each blog post is just a text file with a YAML header and a body. The
+YAML header is surrounded with 2 lines of 3 dashes. This format is
+compatible with [Jekyll][13] and [Github Pages][14].
 
-The **first line** of the header should start with 3 dashes as usual
-for a YAML document.
+The YAML header has following attributes:
 
-The title of your post will be parsed from your first heading
-according to the document type. Shinmun will try to figure out the
-title for Markdown, Textile and HTML files.
-
-The yaml header may have following attributes:
-
-* `date`: post will show up in blog page and archive pages
-* `category`: post will show up in the defined category page
-* `guid`: will be set automatically by Shinmun
-
-Posts without a date are by definition static pages.
+* `title`: mandatory
+* `date`: posts need one, pages not
+* `category`: a post belongs to one category
+* `tags`: a comma separated list of tags
 
 Example post:
 
-<pre>
-
     --- 
-    category: Ruby
     date: 2008-09-05
-    guid: 7ad04f10-5dd6-012b-b53c-001a92975b89
-     
-    BlueCloth, a Markdown library
-    =============================
-
+    category: Ruby
+    tags: bluecloth, markdown
+    title: BlueCloth, a Markdown library
+    ---
     This is the summary, which is by definition the first paragraph of the
     article. The summary shows up in category listings or the index listing.
 
-</pre>
 
-The guid should never change, as it will be you used for identifying
-posts for comments.
+### Syntax highlighting
 
+Thanks to the fantastic highlighting library [CodeRay][4], highlighted
+code blocks can be embedded easily in Markdown. For Textile support
+you have to require `coderay/for_redcloth`. These languages are
+supported: C, Diff, Javascript, Scheme, CSS, HTML, XML, Java, JSON,
+RHTML, YAML, Delphi
 
-### Directory layout
-
-* Your **assets** are in the `assets` folder, which gets copied to the
-  public folder in the render step.
-
-* The **settings of your blog** are defined in `config/blog.yml`
-
-* Your **posts** reside in the `posts` folder sorted by year/month.
+To activate CodeRay for a code block, you have to declare the language
+in lower case:
 
-* Your **pages** are located in the `pages` folder.
+    @@ruby
 
-* **Template** files are in the `templates` folder.
+    def method_missing(id, *args, &block)
+      puts "#{id} was called with #{args.inspect}"
+    end             
 
-* The **index page** of your blog is defined in `pages/index.rhtml` and
-  may be customized.
+**Note that the declaration MUST be followed by a blank line!**
 
-* **Archive pages** will be rendered to files like `public/2008/9/index.html`.
 
-* **Category pages** will be rendered to files like `public/categories/ruby.html`.
-
-
-An example tree:
+### Directory layout
 
     + assets
-      + images
-      + stylesheets
-      + javascripts      
-    + config
-      + blog.yml
+      + print.css
+      + styles.css
+    + config.ru
     + pages
       + about.md
-      + index.rhtml
     + posts
       + 2007
       + 2008
         + 9
           + my-article.md
     + templates
-      + feed.rxml
+      + 404.rhtml
+      + archive.rhtml
+      + category.rhtml
+      + category.rxml
+      + _comments.rhtml
+      + _comment_form.rhtml
+      + index.rhtml
+      + index.rxml
+      + index.rhtml
       + layout.rhtml
-      + page.rhtml  
+      + page.rhtml
       + post.rhtml  
-      + posts.rhtml
-
-
-The output will look like this:
-
-    + public
-      + index.html
-      + about.html
-      + categories
-        + emacs.html
-        + ruby.html
-      + 2007   
-      + 2008
-        + 9
-          + my-article.html
-      + images
-      + stylesheets
-      + javascripts
 
+### Blog configuation
 
-### Config file
+In `config.ru` you can set the properties of your blog:
 
-The configuration of the blog system consists of some variables
-encoded as yaml file:
+    blog.config = {
+      :language => 'en',
+      :title => "Blog Title",
+      :author => "The Author",
+      :categories => ["Ruby", "Javascript"],
+      :description => "Blog description"
+    }
 
-* blog_title: the title of your blog, used for rss
 
-* blog_description: used for rss
-
-* blog_language: used for rss
-
-* blog_author: used for rss, acts also as fallback for the blog.author variable
-
-* blog_url: used for rss
-
-* blog_repository: path for rsync, used for `shinmun push` command
-
-* base_path: if your blog should not be rendered to your site
-  root, you can define a sub path here (like `blog`)
-
-* images_path: used for templates helper, defaults to `images`
-
-* javascripts_path: used for templates helper, defaults to `javascripts`
-
-* stylesheets_path: used for templates helper, defaults to `stylesheets`
-
-* pack_javascripts: a list of scripts to be compressed
-
-* pack_stylesheets: a list of stylesheets to be concatenated
-
-
-### Layout
+### Templates
 
 Layout and templates are rendered by *ERB*.  The layout is defined in
-`layout.rhtml`. The content will be provided in the variable
+`templates/layout.rhtml`. The content will be provided in the variable
 `@content`. A minimal example:
 
     <html>
       <head>
-        <title><%= @blog_title %></title>
+        <title><%= @blog.title %></title>
         <%= stylesheet_link_tag 'style' %>
       </head>
       <body>
@@ -220,95 +151,99 @@ Layout and templates are rendered by *ERB*.  The layout is defined in
       </body>
      </html>
 
+The attributes of a post are accessible via the @post variable:
 
-### Helpers
-
-There are also helper methods, which work the same way like the *Rails*
-helpers. The most important ones are these:
-    
-* `stylesheet_link_tag(*names)` links a stylesheet with a timestamp
-
-* `javascript_tag(*names)` includes a javascript with a timestamp
-
-* `image_tag(src, options = {})` renders an image tag
+    <div class="article">
+     
+      <h1><%= @post.title %></h1>
+     
+      <div class="date">
+        <%= human_date @post.date %>
+      </div>
+     
+      <%= @post.body_html %>
 
-* `link_to(text, path, options = {})` renders a link
+      ...      
 
-Stylesheets, javascripts and images should be included by using theses
-helpers. The helper methods will include a timestamp of the
-modification time as `querystring`, so that the browser will fetch the
-new resource if it has been changed.
+    </div>
 
-If you want to define your own helpers, just define a file named
-`templates/helpers.rb` with a module named `Shinmun::Helpers`. This
-module will be included into the `Shinmun::Template` class.
 
+### Commenting System
 
-### Post Template
+Comments are stored as flat files and encoded as YAML objects. Each
+post has a corresponding comment file located at `comments/<path to
+post>`. So administration of comments is possible by editing the YAML
+file, which can be done on your local machine, as you can just pull
+the comments from your live server.
 
-The attributes of a post are accessible as instance variables in a template:
 
-    <div class="article">    
+### Deployment
 
-      <div class="date">
-        <%= date @date %>
-      </div>
-     
-      <h2><%= @title %></h2>  
-     
-      <%= @body %>
-     
-      <h3>Comments</h3>
+Shinmun can server the blog straight from the git repository. So on
+your webserver initialize a new git repo like:
 
-      <!-- Here you may put my commenting system -->
-    </div>
+    $ cd /var/www
+    $ mkdir myblog
+    $ cd myblog
+    $ git init
 
+Now on your local machine, you add a new remote repository and push
+your blog to your server:
 
-### RSS Feeds
+    $ cd ~/myblog
+    $ git remote add live ssh://myserver.com/var/www/myblog
+    $ git push live
 
-Feeds will be rendered by the *ERB template*
-`templates/feed.rxml`. Some of the variables have been read from the
-`blog.yml`, like `@blog_title`, other variables have been determined
-by the engine like `@posts` or `@category`.
 
+On your production server, you just need the rackup file `config.ru`
+to run the blog:
 
-### Packr Support
+    $ git checkout config.ru
 
-If you set the variables `pack_javascripts` or `pack_stylesheets`,
-Shinmun will create the files `all.js` or `all.css` automatically
-on rendering (even on each request of the webserver).
+Now you can run just a pure ruby server or something like Phusion
+Passenger. Anytime you want to publish a post on your blog, you
+just write, commit and finally push a post by:
 
-The Javascript will be compressed with Packr and for performance
-reasons, minified versions for each of your javascripts will be
-created automatically in `assets/javascripts`.
+    $ git commit -a -m 'new post'
+    $ git push live
 
-The stylesheets will be just concatenated to one file named `all.css`.
 
-Note that you define a yaml array of filenames without file
-extensions, so it should like `[jquery, jquery-form]`.
+### Phusion Passenger
 
+Shinmun is compatible with [Phusion Passenger][5]. Install Phusion
+Passenger as described in my [blog post][2].
 
-### Commenting System
+Assuming that you are on a Debian or Ubuntu system, you can create a
+file named `/etc/apache2/sites-available/blog`:
 
-As I am not willing to build up a whole Rails stack for a single blog,
-I was looking for a simple storage for comments. I really like the
-JSON format. It works seamlessly with Javascript libraries and can be
-serialized and deserialized from almost any language.
+    <VirtualHost *:80>
+        ServerName myblog.com
+        DocumentRoot /var/www/blog/public
+    </VirtualHost>
 
-Read about my [lightweight commenting system][2].
+Enable the new virtual host:
 
+    $ a2ensite myapp
 
-### Download
+After restarting Apache your blog should run on Apache on your desired
+domain:
 
-Simply install the gem:
+    $ /etc/init.d/apache2 restart
 
-    gem install shinmun
 
+### GitHub Project
 
 Download or fork the package at my [github repository][1]
 
 
-
-[1]: http://github.com/georgi/shinmun/tree/master
-[2]: commenting-system-with-lightweight-json-store.html
-[3]: http://github.com/georgi/shinmun-example/tree/master
+[1]: http://github.com/georgi/shinmun
+[2]: http://www.matthias-georgi.de/2008/9/quick-guide-for-passenger-on-ubuntu-hardy.html
+[3]: http://github.com/georgi/kontrol
+[4]: http://coderay.rubychan.de/
+[5]: http://www.modrails.com/
+[6]: http://github.com/rack/rack
+[7]: http://github.com/georgi/git_store
+[8]: http://daringfireball.net/projects/markdown/
+[9]: http://textile.thresholdstate.com/
+[10]: http://en.wikipedia.org/wiki/Html
+[11]: http://www.kernel.org/pub/software/scm/git/docs/git-push.html

data/Rakefile

@@ -1,51 +1,32 @@
-require 'rubygems'
-
 require 'rake'
-require 'rake/clean'
 require 'rake/rdoctask'
-require 'rake/packagetask'
-require 'rake/gempackagetask'
-require 'fileutils'
 
-spec = Gem::Specification.new do |s|
-  s.name = "shinmun"
-  s.version = `git describe`
-  s.platform = Gem::Platform::RUBY
-  s.summary = "a small blog engine"
-  
-  s.description = <<-EOF
-Shinmun is a blog engine, which renders text files using a markup
-language like Markdown and a set of templates into either static web
-pages or serving them over a rack adapter. Shinmun supports
-categories, archives, rss feeds and commenting.
-EOF
-  
-  s.files = `git ls-files`.split("\n").reject { |f| f.match /^pkg/ }
-  s.bindir = 'bin'
-  s.executables << 'shinmun'
-  s.require_path = 'lib'
-  s.add_dependency 'BlueCloth'
-  s.add_dependency 'rubypants'
-  s.has_rdoc = true
-  s.extra_rdoc_files = ['README.md']
-  
-  s.author = 'Matthias Georgi'
-  s.email = 'matti.georgi@gmail.com'
-  s.homepage = 'http://shinmun.rubyforge.org'
-  s.rubyforge_project = 'shinmun'
+begin
+  require 'spec/rake/spectask'
+rescue LoadError
+  puts <<-EOS
+To use rspec for testing you must install the rspec gem:
+    gem install rspec
+EOS
+  exit(0)
+end
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.spec_opts = ['-cfs']
+  t.spec_files = FileList['test/**/*_spec.rb']
 end
 
-Rake::GemPackageTask.new(spec) do |p|
-  p.gem_spec = spec
-  p.need_tar = false
-  p.need_zip = false
+desc "Print SpecDocs"
+Spec::Rake::SpecTask.new(:doc) do |t|
+  t.spec_opts = ["--format", "specdoc"]
+  t.spec_files = FileList['test/*_spec.rb']
 end
 
- 
 desc "Generate RDoc documentation"
 Rake::RDocTask.new(:rdoc) do |rdoc|
   rdoc.options << '--line-numbers' << '--inline-source' <<
-    '--main' << 'README' <<
+    '--main' << 'README.md' <<
     '--title' << 'Shinmun Documentation' <<
     '--charset' << 'utf-8'
   rdoc.rdoc_dir = "doc"
@@ -55,18 +36,5 @@ Rake::RDocTask.new(:rdoc) do |rdoc|
   end
 end
 
-
-task :pdoc => [:rdoc] do
-  sh "rsync -avz doc/ mgeorgi@rubyforge.org:/var/www/gforge-projects/shinmun"
-end
-
-desc "Publish the release files to RubyForge."
-task :release => [ :gem ] do
-  require 'rubyforge'
-  require 'rake/contrib/rubyforgepublisher'
- 
-  rubyforge = RubyForge.new
-  rubyforge.configure
-  rubyforge.login
-  rubyforge.add_release('shinmun', 'shinmun', spec.version, "pkg/shinmun-#{spec.version}.gem")
-end
+desc "Run the rspec"
+task :default => :spec

data/assets/print.css

@@ -0,0 +1,76 @@
+body {
+    line-height:1.5;
+    font-family:"Helvetica Neue", "Lucida Grande", Arial, Verdana, sans-serif;
+    color:#000;
+    background:none;
+    font-size:10pt;
+}
+
+.container {
+    background:none;
+}
+
+h1,h2,h3,h4,h5,h6 {
+    font-family:"Helvetica Neue", Arial, "Lucida Grande", sans-serif;
+}
+
+code {
+    font:.9em "Courier New", Monaco, Courier, monospace;
+}
+
+img {
+    float:left;
+    margin:1.5em 1.5em 1.5em 0;
+}
+
+a img {
+    border:none;
+}
+
+p img.top {
+    margin-top:0;
+}
+
+hr {
+    background:#ccc;
+    color:#ccc;
+    width:100%;
+    height:2px;
+    border:none;
+    margin:2em 0;
+    padding:0;
+}
+
+blockquote {
+    font-style:italic;
+    font-size:.9em;
+    margin:1.5em;
+    padding:1em;
+}
+
+.small {
+    font-size:.9em;
+}
+
+.large {
+    font-size:1.1em;
+}
+
+.quiet {
+    color:#999;
+}
+
+.hide {
+    display:none;
+}
+
+a:link,a:visited {
+    background:transparent;
+    font-weight:700;
+    text-decoration:underline;
+}
+
+a:link:after,a:visited:after {
+    content:" (" attr(href) ") ";
+    font-size:90%;
+}