Soda

Soda is a blogging framework built on Jekyll.

Demo

Running Locally

Soda runs on Jekyll, a blog-aware, static site generator in Ruby. I'm using Ruby 2.1.1 locally. You can run the site with:

$ cd path/to/soda
$ gem install bundler # if you haven't installed Bundler
$ bundle install
$ rake preview

Then open you web browser, visit http://localhost:4000 to see it running. If you have problems getting it up and running, open an issue.

Configuration

All the stuff is placed in _config.yml. I've written plenty of comments there. Just fill in the blanks, run the site and see what happens.

NOTE: Jekyll won't regenrate the site after you change the _config.yml. Therefore, stop and restart the server.

Blogging Basics

Blogging with Soda is pretty easy. All you need is to write posts and type a few built-in commands.

Creating a new post

$ rake create_post[title]

It will create a markdown file under _post/ directory with necessary front-matter variables. Now, go on writing your post.

Generating Site

$ rake build

This rake task lets Jekyll build the static site. If you want to preview the site, just run:

$ rake preview

It will start a web server. The default server address is http://localhost:4000.

Deployment

Soda provides two deployment methods currently. They are rsync and GitHub Pages. Edit the configuration part of the Rakefile before you start.

rsync

$ rake deploy:rsync

GitHub Pages

$ rake deploy:github

For user and orgnization pages, the Rakefile looks like this:

# GitHub pages configuration
github_user = "username"
github_project = "" # Leave this variable empty if you're using user or organization pages
deploy_branch = "master"

For project pages:

# GitHub pages configuration
github_user = "username"
github_project = "project"
deploy_branch = "gh-pages" # For project pages, replace it with "gh-pages"

One more setp, edit the _config.yml.

...

url: "http://username.github.io"
baseurl: "" # Replace it with your project name if you are going to use pages for project

...

assets:
  baseurl: "/assets/" # "/project/assets/" for the same reseason.

...

Other Deployment Methods

Soda can be deployed in a large number of ways due to the static nature of the generated output. The main purpose of them is to put your output onto a web server directory. Since Soda is a Jekyll powered site framework, you can apply any deployment methods suitable for Jekyll. For more details, see the Jekyll documentaion.

Advanced Usage

Assets

Soda uses jekyll-assets, assets pipeline plugin for Jekyll, to manage its assets. If you are familiar with Rails, you must know what I'm talking about. With this poweful plugin, writing Soda becomes much easier. Have a look.

Stylesheets

Soda uses SASS as it's CSS pre-compiler. It also uses an open-souce CSS authoring framework, Compass. All the stylesheets are placed in _assets/stylesheets/.

Write your own CSS there. I'd like to see your awesome works.

Javascripts

There are 3 main Javascripts: jQuery.js, FitVids.js and Skrollr.js.

• FitVids.js is a lightweight, easy-to-use jQuery plugin for fluid width video embeds.
• Skrollr.js is a stand-alone parallax scrolling library for mobile (Android + iOS) and desktop.

app.js is the js file for the whole site and plugins.js is where any jQuery plugins should be. Feel free to add your code.

Images

All the site related image content is placed under _assets/images/. You may want to use you own artworks. One thing you should beware of is that any images which appear in posts ought to be placed under images/ directory or just URL links. Keeping the site content in _post/ and images makes life easier.

NOTE: If you prefer putting your images under _assets/images/ directory. Use the Liquid tag {% image 'your-image.jpg' %} or the corresponding filter {{ 'your-image.jpg' | image }} in your source files (either HTML or markdown file). To get the relative path, invoke {% asset_path 'your-image.jpg' %} or {{ 'your-image.jpg' | asset_path }}.

Fonts

The icon fonts are generated by IcoMoon, an excellent site for building custom fonts. Feel free to replace them as you like.

Templates

As a typical Jekyll site, all the layouts and html partials are in the right place. Have a try.

Cover Images

Soda likes cover images. They are cool. Soda won't resize your image currently, so take image size into consideration. Neither too large nor too small.

Credits

Soda is created by Yiming Tang. It's built on Jekyll, a blog-aware, amazing static site generator, without which Soda can't be here.

Soda is inspired by many websites, frameworks and themes. They are:

• Roon made by Drew Wilson and Sam Soffes.
• Medium.
• Octopress, a blogging platform for hackers, designed by Brandon Mathis.
• Poole, the butler for Jekyll, designed by @mdo.
• Casper, the default theme for Ghost.

Soda also uses a lot of powerful Ruby gems and Jekyll plugins. I'd like to say thank you to all of the smart brains.

License

The source code of Soda is released under the MIT License. See LICENSE for more information.

All image content that Soda uses remain copyright its original copyright holder.