REVISION

Revision is a blogging system built on top of git. Each commit is visualized as a blog post. Contrary to traditional blogs, the point of revision is not to release finished articles all at once, but to let your audience follow your process of writing them.
Here's an example of how this could look like.

Setting up Revision

You'll need:

• Ruby (> 2.3.1)
• Rails (> 5.1.4)

1. Clone or download the repository and cd there.
2. $ bundle install
3. In config/application.rb, adjust

   config.x.repo = "/path/to/repository"

   to make it point to your blog repository.
4. (Optional) To deploy Revision in a sub-directory (e.g. mydomain.com/blog), adjust this line like so:

   config.relative_url_root = "/blog"

   A corresponding Nginx configuration can be found here.
5. $ ./bin/rails server

Setting up the blog repository

1. Have a local git repository that is accessible by your Revision instance.
   You can do this by:
   1. Setting up your own server and cloning.
      Suggested read: Setting up a git hook for automating updates.
   2. Setting up a local repository and make your edits directly there. (no remote needed)
   3. Hosting the repo remotely and cloning.
2. Your repository shoud have a structure like this:

   blog/ (project root)
   |   revision.yml
   |
   └── category1/
   |   |   Hello_World.md
   |   |   My_Other_Article.md
   |   |
   |   └── media/
   |       |   helloworld.jpg
   |
   └── category2/
   |   ...
   

3. Populate revision.yml

Configuration

### revision.yml

# The blog's title
title: My Awesome Blog

# As this is git, you cannot "delete" a post,
# but you can place it here and Revision won't render it.
# A file will be ignored, if its name+path (relative to blog root)
# contains an entry of this list as a substring.
ignore:
  - 10_Reasons_why_Nickleback_rock
  - category1/My_Other_Article.md

Remember to restart Revision after editing this file.

Authoring articles

• Revision articles are written in markdown, but you can also use inline html. I would suggest to use markdown as much as possible though.
• Filename equals Title (underscores replaced by spaces), so choose them carefully.
• Embedding images that reside within the blog repository should be done like so:

  ### Hello_World.md
  
  [Alternative text](/media/helloworld.jpg "Caption")

  Revision will automatically resolve such paths relative to the article.
• Use meaningful commit messages, as they will appear in the timeline of your article.
• Hints:
  • Get familiar with git's --amend option. You will use it frequently.
  • Start a new line as often as possible, so that git can make precise diffs. You can do that safely, as markdown doesn't render line breaks a without double space anyway.

Commands

You can place these commands anywhere in the commit message:

• --hide Don't show this commit in the feed and the timeline. You can use this e.g. for spelling corrections if it is too late to just --amend the last commit.
• --tag="tag name" Tag a version of your article. A tagged version will be highlighted in the acticle's timeline. (not yet implemented)