Shinmun, a small and beautiful 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. ### 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 * AJAX comment system with Markdown preview ### Quickstart Install the gem: gem install shinmun Download shinmun-example from my [github repository][3] and type: tar xvzf shinmun-example.tar.gz cd shinmun-example rackup Now browse to the following url: http://localhost:9292 Voilà, your first blog is up and running! ### Writing Posts Posts can be created by using the `shinmun` command inside your blog folder: shinmun new '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 probably open the file, set the category and tags and start writing 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. The **first line** of a post should consist of 3 dashes to mark the YAML header. 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 Example post: --- date: 2008-09-05 category: Ruby tags: bluecloth, markdown, ruby 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 To activate CodeRay for a code block, you have to declare the language in lower case: @@ruby def method_missing(id, *args, &block) puts "#{id} was called with #{args.inspect}" end **Note that the declaration MUST be followed by a blank line!** ### Directory layout * `assets`: like images, stylesheets and javascripts * `comments`: comments stored as yaml files * `config`: configuration of blog, aggregations, assets and categories * `posts`: post files sorted by year/month. * `pages`: contains static pages * `templates`: ERB templates for layout, posts and others An example tree: + assets + images + stylesheets + javascripts + config + aggregations.yml + assets.yml + blog.yml + categories.yml + pages + about.md + posts + 2007 + 2008 + 9 + my-article.md + templates + category.rhtml + category.rxml + comments.rhtml + feed.rxml + helpers.rb + index.rhtml + index.rxml + layout.rhtml + post.rhtml ### Blog configuation Inside `config/blog.yml` you will 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 * 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 * javascripts_files: a list of scripts to be compressed to `all.js` * stylesheets_files: a list of stylesheets to be concatenated to `all.css` ### 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 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: <%= @blog.title %> <%= stylesheet_link_tag 'style' %> <%= @content %> ### 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:
<%= date @date %>

<%= @title %>

<%= @body %>

Comments

### 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/`. So administration of comments is possible by editing the YAML file, you can even version control your comments if you want. ### Static Output 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. 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/`. ### 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: $ rackup 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. ### Phusion Passenger Shinmun is already 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`: ServerName myblog.com DocumentRoot /var/www/blog/public Enable the new virtual host: $ a2ensite myapp After restarting Apache your blog should run on Apache on your desired domain: $ /etc/init.d/apache2 restart ### Download Download or fork the package at my [github repository][1] [1]: http://github.com/georgi/shinmun/tree/master [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 [4]: http://coderay.rubychan.de/ [5]: http://www.modrails.com/