Skip to content

Latest commit

 

History

History
178 lines (133 loc) · 8.7 KB

README.mkdn

File metadata and controls

178 lines (133 loc) · 8.7 KB

git-blog Maintenance statusCode quality and healthOpen-source licensing detailsChat on FreenodeTwitter followers

git-blog intends to be blogging, simplified. You'll write your posts in your favorite text editor, with your favorite markup. Then save the post's file, git add the post, and then git push origin master. git-blog, running on your server, will catch the push and parse the post to your static HTML blog. Fast, no dynamic code being run on every load, free post versioning (git revisions), free sections (git branches), freedom of mind.

If you wish to discuss git-blog, or just hang around, feel free to join the #ELLIOTTCABLE channel on Freenode (make sure to say his name to get his attention!)

Philosophy & goals

git-blog will never be featureful, but it will also never be bloated. I doubt I will ever do anything more than parsing the posts to static HTML on every git push.

Note: This project is functional, but not under active development (as is probably obvious from the last-modified dates above.) If anything breaks, please feel free to open an issue or mention it in the IRC channel above. Feature requests are likely to go unfulfilled; but pull-requests are welcome. (=

Getting

The authoritative source for this project is available at http://github.com/elliottcable/git-blog. You can clone your own copy with the following command:

git clone git://github.com/elliottcable/git-blog.git

If you want to make changes to the codebase, you need to fork your own github repository for said changes. Send a pullrequest to elliottcable when you've got something ready for the master that you think should be integrated into the root source.

This project has been forked several times with different goals. Due to an almost draconian anti-bloat policy, as well as other concerns (see the History section below), these haven't been (and probably never will be) merged into the origin repository. One fork worth checking out is evaryont's, which is the official maintained-stable fork of git-blog's original, ultra-simple Rakefile format.

This project is released for public usage under the terms of the very-permissive ISC license (a modern evolution of the MIT / BSD licenses); more information is available in COPYING.

Preparing git-blog

To prepare a new git-blog, run this task from the cloned git-blog repository, replacing ~/Documents/Blog (my personal favorite location) the name of the folder where you want your blog to exist locally:

rake create[~/Documents/Blog]

After this is complete, move to that folder (something along the lines of cd ~/Documents/Blog), and then add any remote repositories to which you wish to push your blog. Most likely, this will include the server hosting your blog to the web. The simplest setup to push to this server is an SSH connection - if you have SSH access to your server/host, you can run this to set up git-blog for pushing:

git remote add blog username@host.tld:/path/to/server/blog/folder

This will prepare a remote named 'blog' to which you can push your changes. In addition, if you use GitHub, you can also push your blog there. Create a new repository on GitHub, and then use this to automatically set up that remote for you:

rake github[github_username,github_repo]

Now, you'll want to set up the server to host git-blog - this is fairly simple, about equable to setting up git-blog locally. The only addition, after creating the blog's directory on the server the same as you did locally (rake create[/path/to/server/blog/folder], from within the git-blog clone dir on your server), is preparing the post-receive hook. It's really simple - change directory to your new blog's folder on the server, and run this:

rake servable

Using git-blog

Once your new blog is prepared, you'll want to write a post. Writing a new post is quite simple - run rake post, and it will open your favorite $EDITOR with a post prepared to edit.

You're free to format your blog posts however you want - at the moment there are parsers set up for Markdown, Textile, and Haml - and support for plain text and plain X)HTML. The only restriction when formatting, is that your post's title is on the very first line, formatted plainly in whatever way your parser supports. This title will not appear in the final post, and will instead be sent to the post template.

Once you've finished editing your post, save it, and close the window or exit the editor (whatever is appropriate for your editor of choice) - it will automatically add the new post to the index, and then commit it. You can repeat this process if you want to post more posts before pushing them to the server.

Now just push your beautiful new post(s) to the server:

git push blog

I suggest you run rake deploy before committing any new posts / changes to post - if you have a syntax error in one of your posts, the parser may not like it, and it's preferable to catch this before you commit the changes and push them to your blog.

git-blog will automatically re-parse all of your posts, and create an index file for your blog, after you git push to the server. They're going to end up as simple static HTML, so there's nearly no load on your server when a page is visited - this makes a git-blog inherently faster and cheaper to run than any dynamic blog (such as Wordpress or Expression Engine) could ever be.

Customizing git-blog

Your git-blog's design is all stored in the same repository as your posts - it consists of, simply, two Haml files that are rendered with the posts. One, post.haml, is the layout framework into which your posts' content will be pushed; and the other, index.haml, is the framework for the index page of your blog. Customizing the look and feel of your blog is as simple as modifying these two files to your liking, see the defaults for an example.

The git-blog rakefile itself is meant to be very hackable, and if you want to add further functionality - a different parsing system for your favorite markup, or extensions to the existing parsers for your frequently-used markup, or new blog features such as comments, trackbacks, feeds, and so on... it's as simple as fiddling around with git-blog's core. Don't be afraid, it's meant to be broken! If you do end up adding something cool to git-blog, I would very much appreciate it if you told me, I'll gladly link to your github fork from this README for other users to see.

Requirements

To run git-blog, you need git (obviously) - on a Macintosh, you can install it using MacPorts as follows:

sudo port install git-core

On a Linux or Windows machine, you're a bit more on your own, as I don't know how to install it on Windows, and I'm assuming a person using a Linux distrib is proficient enough to figure it out. In addition, you need the following gems:

  • gem install git
  • gem install haml
  • gem install RedCloth (if you wish to write your posts in Textile)
  • One of the following Markdown libraries (if you wish to write your posts in Markdown)
    • sudo gem install rdiscount
    • sudo gem install rpeg-markdown
    • sudo gem install maruku
    • sudo gem install BlueCloth

To develop and contribute to git-blog, you also need:

  • gem install rspec
  • gem install rake
  • gem install rcov
  • gem install technomancy-ditz --source=http://gems.github.com