georgi-shinmun 0.3 → 0.3.1

data/README.md

@@ -1,43 +1,38 @@
-Shinmun, a small and beautiful blog engine
+Shinmun, the git-based blog engine
 ==========================================
 
 Shinmun is a **minimalist blog engine**. You just write posts as text
-files and serve your blog via rack handler or static files.
-
-This allows you to write posts in your favorite editor like Emacs or
-VI and use a VCS like git.
-
-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.
-
+files and serve your blog straight from a git repository. You write
+posts in your favorite editor like Emacs or VI and deploy via 
+`git push`.
 
 ### Features
 
-* Index listing
-* Category listing
-* Archive listings for each month
-* RSS feeds for index and category pages
-* Rack handler for realtime rendering
-* Phusion Passenger compatible
-* Compression of javascript files with PackR
-* Syntax highlighting for many languages provided by CodeRay
+* Index, category and archive listings
+* RSS feeds
+* Flickr and Delicious aggregations
+* Runs on Rack via [Kontrol][3]
+* Syntax highlighting provided by CodeRay
 * AJAX comment system with Markdown preview
 
-
 ### Quickstart
 
-Install the gem:
+Install the gems:
 
-    gem install shinmun
+    $ gem sources -a http://gems.github.com
+    $ gem install rack BlueCloth rubypants coderay mojombo-grit georgi-git_store georgi-kontrol georgi-shinmun
 
-Download shinmun-example from my [github repository][3] and type:
+Create a sample blog (this step requires the git executable):
 
-    tar xvzf shinmun-example.tar.gz
-    cd shinmun-example
-    rackup
+    $ shinmun init myblog
+
+This will create a directory with all necessary files. Now start the
+web server:
+
+    $ cd myblog
+    $ rackup
 
-Now browse to the following url:
+Browse to the following url:
 
     http://localhost:9292
 
@@ -49,7 +44,7 @@ Voilà, your first blog is up and running!
 Posts can be created by using the `shinmun` command inside your blog
 folder:
 
-    shinmun new 'The title of the post'
+    shinmun post 'The title of the post'
 
 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
@@ -59,55 +54,35 @@ your new article.
 
 ### Post Format
 
-Each blog post is just a text file with an header section and a markup
-body, which are separated by a newline.
+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.
 
-The **first line** of a post should consist of 3 dashes to mark the
-YAML header.
+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:
-
-* `title`: if you have no title inside the markup, you have to define it here
-* `date`: needed for chronological order and for archive pages
-* `category`: needed for category pages
-* `tags`: used to determine similar posts
+* `title`: mandatory
+* `date`: posts need one, pages not
+* `category`: a post belongs to one category
+* `tags`: a comma separated list of tags
 
 Example post:
 
     --- 
     date: 2008-09-05
     category: Ruby
-    tags: bluecloth, markdown, ruby
-     
-    BlueCloth, a Markdown library
-    =============================
-
+    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.
 
 
 ### 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
+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
 
 To activate CodeRay for a code block, you have to declare the language
 in lower case:
@@ -123,21 +98,18 @@ in lower case:
 
 ### Directory layout
 
-* `assets`: like images, stylesheets and javascripts
-
-* `comments`: comments stored as yaml files
-
-* `config`: configuration of blog, aggregations, assets and categories
-
+* `assets`: contains images, stylesheets and javascripts
+* `comments`: comments are stored as yaml files
+* `config`: configuration of blog, aggregations and assets
 * `posts`: post files sorted by year/month.
-
 * `pages`: contains static pages
-
 * `templates`: ERB templates for layout, posts and others
 
-
 An example tree:
 
+    + config.ru
+    + map.rb
+    + helpers.rb
     + assets
       + images
       + stylesheets
@@ -146,7 +118,6 @@ An example tree:
       + aggregations.yml
       + assets.yml
       + blog.yml
-      + categories.yml
     + pages
       + about.md
     + posts
@@ -157,72 +128,45 @@ An example tree:
     + templates
       + category.rhtml
       + category.rxml
-      + comments.rhtml
+      + _comments.rhtml
+      + _comment_form.rhtml
       + feed.rxml
       + helpers.rb
       + index.rhtml
       + index.rxml
       + layout.rhtml
       + post.rhtml  
+      + page.rhtml
 
 
 ### Blog configuation
 
-Inside `config/blog.yml` you will set the properties of your blog:
+Inside `config/blog.yml` you set the properties of your blog:
 
 * title: the title of your blog, used inside templates
-
 * description: used for RSS
-
 * language: used for RSS
-
 * author: used for RSS
-
 * url: used for RSS
+* categories: a list of categories
 
-* 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`)
-
-
-### Asset configuation
-
-If you set the variables `javascripts_files` or `stylesheets_files`,
-Shinmun will compress the javascripts to `all.js` and concatenate all
-stylesheets to `all.css` automatically.
-
-* images_path: used for templates helper
-
-* javascripts_path: used for templates helper
-
-* stylesheets_path: used for templates helper
+### Assets
 
-* javascripts_files: a list of scripts to be compressed to `all.js`
+By default Shinmun serves asset files from your assets directory. If
+you want some other behaviour, you can tweak the `map.rb` file in your
+blog folder, which contains all routes.
 
-* stylesheets_files: a list of stylesheets to be concatenated to `all.css`
+If you set the variables `javascripts_files` or `stylesheets_files` in
+`config/asstes.yml`, Shinmun will serve the javascripts as
+`assets/javascripts.js` and stylesheets as `assets/stylesheets.css`
+automatically. Both variables should be arrays of the filenames
+without extension.
 
-
-### Categories
-
-You have to list your categories in `config/categories.yml`. This will
-look like:
-
-    ---
-    categories:
-      - { name: Ruby }
-      - { name: Javascript }
-
-You may define arbitrary properties for each category, which then can
-be accessed inside the templates. For example you could add a
-description and use it inside the `templates/category.rhtml`.
-
-
-### Layout
+### Templates
 
 Layout and templates are rendered by *ERB*.  The layout is defined in
 `templates/layout.rhtml`. The content will be provided in the variable
-`@content`. A minimal but functional example:
+`@content`. A minimal example:
 
     <html>
       <head>
@@ -234,105 +178,65 @@ Layout and templates are rendered by *ERB*.  The layout is defined in
       </body>
      </html>
 
-
-### 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
-
-* `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.
-
-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.
-
-
-### Post Template
-
-The attributes of a post are accessible as instance variables in a template:
+The attributes of a post are accessible as instance variables in a
+template:
 
     <div class="article">    
-
       <div class="date">
         <%= date @date %>
       </div>
-     
       <h2><%= @title %></h2>  
-     
       <%= @body %>
-     
       <h3>Comments</h3>
-
       <!-- comment form -->
     </div>
 
 
 ### Commenting System
 
-Commenting is only available in the rack handler. 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, you
-can even version control your comments if you want.
+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.
 
+### Deployment
 
-### Static Output
+Shinmun can server the blog straight from the git repository. So on
+your webserver initialize a new git repo like:
 
-To render your complete blog you may run `shinmun render` and the
-output will be rendered to the `public` folder. Note that in this case
-you will miss some dynamic features like the commenting system.
+    $ cd /var/www
+    $ mkdir myblog
+    $ cd myblog
+    $ git init
 
-By issuing the `shinmun push` command your blog will be pushed to your
-server using rsync. This works only, if you define the `repository`
-variable inside `config/blog.yml`. It should contain something like
-`user@myhost.com:/var/www/my-site/`.
+Now on your local machine, you add a new remote repository and push
+your blog to your server:
 
+    $ cd ~/myblog
+    $ git remote add live ssh://myserver.com/var/www/myblog
+    $ git push live
 
-### Realtime Rendering
 
-Shinmun features a lightweight rack handler, which lets you run your
-blog in almost any environment. In `shinmun-example` you will find a
-rackup file called `config.ru`. To start the standalone server just
-run:
+On your production server, you just need the rackup file `config.ru`
+to run the blog:
 
-    $ rackup
+    $ git checkout config.ru
 
-Browse to `http://localhost:9292` and you will see your blog served in
-realtime. Just change any of your posts, templates or settings and you
-will see the new output in your browser. Even the javascripts and
-stylesheets will be packed at runtime if you configured it. Shinmun
-caches all files, so that everything get served from memory.
+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:
 
+    $ git commit -a -m 'new post'
+    $ git push live
 
 ### Phusion Passenger
 
-Shinmun is already compatible with [Phusion Passenger][5]. Install Phusion
+Shinmun is compatible with [Phusion Passenger][5]. Install Phusion
 Passenger as described in my [blog post][2].
 
-Now copy your blog folder to some folder like `/var/www/blog` and
-create a sub directory `public`. Inside this directory you should link
-your assets folders:
-
-    # cd public
-    # ln -s ../assets/images
-    # ln -s ../assets/javascripts
-    # ln -s ../assets/stylesheets
-
-This is just to ensure that static files will be served by Apache.
-
-Assuming that you are on a Debian or Ubuntu system, you can now create
-a file named `/etc/apache2/sites-available/blog`:
+Assuming that you are on a Debian or Ubuntu system, you can create a
+file named `/etc/apache2/sites-available/blog`:
 
     <VirtualHost *:80>
         ServerName myblog.com
@@ -349,13 +253,32 @@ domain:
     $ /etc/init.d/apache2 restart
 
 
+### Web Frontend
+
+The example blog has a builtin web frontend. To activate you have to
+create a file named `password` with a single password inside. Now
+browse to `/admin` and login using some arbitrary username and your
+password.
+
+The frontend allows you to create, edit, read or delete posts or
+pages. Editing a post shows up a form with the [wmd editor][6]. You
+have to look yourself for a correct YAML header, otherwise you will
+get incorrect results.
+
+One nice thing about the frontend is the *Commits* page, where you can
+look at a list of recent commits. Clicking on a commit brings you to a
+single commit overview, where you can inspect changes introduced by
+this particular commit.
+
+
 ### Download
 
 Download or fork the package at my [github repository][1]
 
 
-[1]: http://github.com/georgi/shinmun/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/shinmun-example/tree/master
+[3]: http://github.com/georgi/kontrol
 [4]: http://coderay.rubychan.de/
 [5]: http://www.modrails.com/
+[6]: http://wmd-editor.com/

data/bin/shinmun

@@ -7,6 +7,14 @@ when 'init'
   Shinmun::Blog.init ARGV[1]
 
 when 'post'
+  Shinmun::Blog.new.create_post(:title => ARGV[1], :date => Date.today)
+
+when 'page'
   Shinmun::Blog.new.create_post(:title => ARGV[1])
 
+else
+  puts "Usage:"
+  puts "  shinmun init dir - creates a new blog"
+  puts "  shinmun post 'Title of the post' - create a new post"
+  puts "  shinmun page 'Title of the page' - create a new page"
 end

data/lib/shinmun/blog.rb

@@ -11,7 +11,7 @@ module Shinmun
     config_reader 'blog.yml', :title, :description, :language, :author, :url, :repository, :base_path, :categories
 
     # Initialize the blog
-    def initialize(&block)
+    def initialize
       super
 
       @aggregations = {}
@@ -51,11 +51,11 @@ module Shinmun
     end
 
     def recent_posts
-      posts.sort_by { |post| post.date }.reverse[0, 20]
+      posts.sort_by { |post| post.date.to_s }.reverse[0, 20]
     end
 
     def posts_by_date      
-      posts.sort_by { |post| post.date }.reverse
+      posts.sort_by { |post| post.date.to_s }.reverse
     end
 
     # Return all posts for a given month.
@@ -98,10 +98,11 @@ module Shinmun
       store.commit(message)
     end
 
-    # Create a new post with given title.
+    # Create a new post with given attributes.
     def create_post(atts = {})
       atts = { :type => 'md' }.merge(symbolize_keys(atts))
-      atts[:name] = urlify(atts[:title]) or raise "no title given"
+      title = atts[:title] or raise "no title given"
+      atts[:name] ||= urlify(title)
       post = Post.new(atts)
       tree_for(post)[post.filename] = post
       commit "created `#{post.title}`"

data/lib/shinmun/post.rb

@@ -7,10 +7,8 @@ module Shinmun
   #     --- 
   #     category: Ruby
   #     date: 2008-09-05
-  #      
-  #     BlueCloth, a Markdown library
-  #     =============================
-  #
+  #     title: BlueCloth, a Markdown library
+  #     ---
   #     This is the summary, which is by definition the first paragraph of the
   #     article. The summary shows up in list views and rss feeds.  
   #
@@ -25,15 +23,15 @@ module Shinmun
       end
     end
 
-    attr_accessor :name, :type, :title, :src, :head, :body, :summary, :body_html, :tag_list
-    head_accessor :author, :date, :category, :tags, :languages, :header
+    attr_accessor :name, :type, :src, :head, :body, :summary, :body_html, :tag_list
+    head_accessor :title, :author, :date, :category, :tags
 
     # Initialize empty post and set specified attributes.
     def initialize(attributes={})
       @head = {}
       @body = ''
       
-      for k, v in attributes
+      attributes.each do |k, v|
         send "#{k}=", v
       end
 
@@ -80,60 +78,30 @@ module Shinmun
     end
 
     # Split up the source into header and body. Load the header as
-    # yaml document. Render body and parse the summary from rendered html.
+    # yaml document if present.
     def parse(src)
-      src = src.delete("\r")
-
-      # Parse YAML header if present
-      if src =~ /\A(---.*?)\n\n(.*)/m
+      if src =~ /\A(---.*?)---(.*)/m
         @head = YAML.load($1)
         @body = $2
       else
         @body = src
       end
 
-      @title = head['title'] or parse_title
-      @body_html = transform(body)
+      @body_html = transform(@body)
       @summary = body_html.split("\n\n")[0]
       @tag_list = tags.to_s.split(",").map { |s| s.strip }
 
       self
     end
 
-    # Parse title from different formats
-    def parse_title
-      lines = body.split("\n")
-
-      return if lines.empty?
-
-      case type
-      when 'md'
-        @title = lines.shift.sub(/(^#+|#+$)/,'').strip
-        lines.shift if lines.first.match(/^(=|-)+$/)
-
-      when 'html'
-        @title = lines.shift.sub(/(<h1>|\<\/h1>)/,'').strip
-
-      when 'tt'
-        @title = lines.shift.sub(/(^h1.)/,'').strip
-      end
-
-      @body = lines.join("\n")
+    # The header as yaml string.
+    def dump_head
+      head.empty? ? '' : head.to_yaml + "---\n"
     end
 
     # Convert to string representation
     def dump
-      str = head.empty? ? '' : head.to_yaml + "\n"
-      unless head['title']
-        str << \
-        case type
-        when 'md'   : "#{title}\n#{'=' * title.size}\n"
-        when 'html' : "<h1>#{title}</h1>\n"
-        when 'tt'   : "h1.#{title}\n"
-        else raise
-        end
-      end
-      str + body
+      dump_head + body
     end
 
     # Transform the body of this post. Defaults to Markdown.

data/lib/shinmun/post_handler.rb

@@ -1,7 +1,7 @@
 module Shinmun
 
   class PostHandler
-    def read(id, name, data)
+    def read(name, data)
       Post.new(:filename => name, :src => data)
     end
 
@@ -13,5 +13,3 @@ module Shinmun
 end
 
 GitStore::Handler['md'] = Shinmun::PostHandler.new
-
-

data/lib/shinmun.rb

@@ -1,15 +1,12 @@
 require 'rubygems'
 require 'fileutils'
-
 require 'bluecloth'
 require 'rubypants'
 require 'coderay'
-require 'packr'
-require 'grit'
+require 'kontrol'
 
 begin; require 'redcloth'; rescue LoadError; end
 
-require 'kontrol'
 require 'shinmun/bluecloth_coderay'
 require 'shinmun/helpers'
 require 'shinmun/blog'

data/test/blog_spec.rb

@@ -31,11 +31,13 @@ describe Shinmun::Blog do
     file 'map.rb', File.read(TEST_DIR + '/map.rb')
     
     Dir.mkdir 'templates'
+    
     Dir[TEMPLATES_DIR + '/*'].each do |path|      
       unless path.include?('~')
         file 'templates/' + File.basename(path), File.read(path)
       end
-    end   
+    end
+    
     @blog.store.load
     
     @posts = [@blog.create_post(:title => 'New post', :date => '2008-10-10', :category => 'Ruby', :body => 'Body1'),
@@ -44,7 +46,7 @@ describe Shinmun::Blog do
 
     @pages = [@blog.create_post(:title => 'Page 1', :body => 'Body1'),
               @blog.create_post(:title => 'Page 2', :body => 'Body2')]
-    
+
     @blog.store.load
   end
 
@@ -66,7 +68,17 @@ describe Shinmun::Blog do
 
   def xpath(xml, path)
     REXML::XPath.match(REXML::Document.new(xml), path)
-  end  
+  end
+  
+  def assert_listing(xml, list)
+    titles = xpath(xml, "//h2/a")
+    summaries = xpath(xml, "//p")
+
+    list.each_with_index do |(title, summary), i|
+      titles[i].text.should == title
+      summaries[i].text.strip.should == summary
+    end
+  end
 
   it "should find posts for a category" do
     category = @blog.find_category('ruby')
@@ -92,7 +104,7 @@ describe Shinmun::Blog do
 
   it "should update a post" do
     post = @blog.create_post(:title => 'New post', :date => '2008-10-10')
-    @blog.update_post(post, "---\ndate: 2008-11-11\n\nThe title\n=========\n")
+    @blog.update_post(post, "---\ndate: 2008-11-11\ntitle: The title\n---")
     @blog.store.load
     
     post = @blog.find_post(2008, 11, 'new-post')
@@ -117,16 +129,6 @@ describe Shinmun::Blog do
     xpath(xml, "//p")[0].text.should == 'Body1'
   end
 
-  def assert_listing(xml, list)
-    titles = xpath(xml, "//h2/a")
-    summaries = xpath(xml, "//p")
-
-    list.each_with_index do |(title, summary), i|
-      titles[i].text.should == title
-      summaries[i].text.strip.should == summary
-    end
-  end
-
   it "should render categories" do
     get('/categories/ruby.rss')['Content-Type'].should == 'application/rss+xml'
 
@@ -149,7 +151,7 @@ describe Shinmun::Blog do
   end
 
   it "should render pages" do
-    xml = get('/page-1').body    
+    xml = get('/page-1').body
     xpath(xml, "//h1")[0].text.should == 'Page 1'
     xpath(xml, "//p")[0].text.should == 'Body1'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: georgi-shinmun
 version: !ruby/object:Gem::Version 
-  version: "0.3"
+  version: 0.3.1
 platform: ruby
 authors: 
 - Matthias Georgi