Build a Powerful Blog with RefineryCMS: A Beginner‘s Guide

If you‘re looking to build a blog or content-driven website, a CMS (content management system) is the way to go. While mega-popular options like WordPress or Drupal might seem like the default choice, they‘re far from the only options out there.

If you‘re comfortable with Ruby on Rails development (or eager to learn), RefineryCMS is a powerful, flexible CMS built on Rails that‘s well-suited for blogs and other content-heavy sites. It offers an intuitive admin panel for content editors, a blogging engine, plus a wide range of plugins and customization options for developers.

In this guide, we‘ll walk through the process of building a blog-powered website with RefineryCMS from start to finish. We‘ll cover:

  • An intro to RefineryCMS and its key features
  • How to install and set up a new RefineryCMS project
  • Adding blog functionality with the refinerycms-blog engine
  • Customizing your blog‘s design with the ZURB Foundation framework
  • Deploying your shiny new RefineryCMS blog
  • Examples of sites built with Refinery for inspiration
  • Resources to dig deeper and get help when you need it

Whether you‘re a Rails developer looking to add content management capabilities to your toolkit or a blogger seeking a flexible, fully-customizable alternative to WordPress, this guide will give you a solid foundation for building with RefineryCMS. Let‘s dive in!

Why RefineryCMS?

Before we get into the nitty-gritty of building with Refinery, let‘s take a step back and look at what makes this CMS unique and why you might choose it over other options.

The biggest thing that sets RefineryCMS apart is that it‘s built with Ruby on Rails. Unlike PHP-based systems like WordPress and Drupal, Refinery is written in Ruby and deeply integrated with the Rails ecosystem.

So if you‘re already comfortable working in Rails, Refinery will feel very familiar. You‘ll be able to customize your site using standard Rails conventions and tap into the wealth of gems and plugins out there. With WordPress or Drupal, you‘d need to learn their unique plugin systems and templating languages.

Even if you‘re new to Rails, RefineryCMS is a great way to dive in and get some real-world experience building a Rails-based app. The CMS provides a ready-made foundation so you can focus on customizing the features and design to fit your needs.

Some other key benefits of RefineryCMS:

  • Intuitive, user-friendly admin interface for content editors
  • Powerful templating system and custom page builder
  • Extensions for common functionality like forms, search, blog, e-commerce, etc.
  • Ability to easily import content from WordPress
  • Large collection of open source themes and plugins
  • Active developer community and good documentation

Of course, no CMS is one-size-fits-all. WordPress and Drupal are still very good options, especially for less tech-savvy users or very large, complex sites.

But if you want full control over your site and you‘re up for a bit of a learning curve, RefineryCMS is an excellent choice. You‘ll be able to build a totally custom site without having to start from scratch.

Installing RefineryCMS

Convinced that RefineryCMS is the way to go? Great! Let‘s get it installed so you can start building.

The official Refinery docs have a very thorough guide to installing the CMS. But here‘s a quick overview of the steps:

  1. Make sure you have Ruby, RubyGems, and Ruby on Rails set up on your machine. Refinery requires at least Ruby 2.0 and Rails 4.0.
  2. Install ImageMagick, which is required for image processing in Refinery.
  3. Install the RefineryCMS gem:
    gem install refinerycms
  4. Generate a new Refinery project:
    refinerycms project_name
  5. Set up your database and run the Refinery database migrations
  6. Start up your local Rails server and visit http://localhost:3000 to see your new Refinery site!

The installer provides a number of options for customizing your install, like setting up your site in a subdirectory or creating an "About" page. You can also choose to skip the default Refinery frontend and start with a completely blank slate.

For the purposes of this guide, we‘ll assume you‘re starting with the default Refinery install, but feel free to tweak the options to suit your needs.

Adding a Blog to Your RefineryCMS Site

Now that you‘ve got a basic Refinery site up and running, let‘s add some blogging functionality.

RefineryCMS doesn‘t include a blog engine out of the box, but adding one is as easy as installing the refinerycms-blog gem. Just follow these steps:

  1. Add the gem to your Gemfile:
    gem ‘refinerycms-blog‘, git: ‘https://github.com/refinery/refinerycms-blog‘, branch: ‘master‘
  2. Install the gem and run the Refinery blog generator:
    bundle install
    rails generate refinery:blog
  3. Run the database migrations to add the required blog tables:
    rake db:migrate
  4. Optional: Seed your blog with some sample posts:
    rake db:seed

And just like that, you‘ve got a fully-featured blog added to your RefineryCMS site! To access the blog admin panel, log into your Refinery admin area and you‘ll see a new "Blog" tab in the left sidebar.

From there, you can create, edit, and manage your blog posts, categories, and comments just like any other content in Refinery. The engine also comes with a set of templates for displaying your blog posts, archive pages, and RSS feed on the front-end of your site.

Some of the key features of the refinerycms-blog engine include:

  • WYSIWYG editing with image and file uploading
  • Tagging, categories, and featured images for posts
  • Configurable comment moderation (including Disqus and IntenseDebate support)
  • Customizable URL slugs for posts
  • Built-in share links for Twitter, Facebook, and Google+
  • Multilingual support
  • Front-end post searching
  • Flexible templating for customizing the display
  • Support for multiple blogs per site (e.g. subdomains)

The default install will get you up and running quickly, but take some time to explore the extensive configuration options to make the blog your own.

Make It Pretty: Customizing Your Blog‘s Look and Feel

Front-end developers will be happy to hear that RefineryCMS is built to be customized. You‘ve got full control over the HTML, CSS, and JavaScript to make your site look exactly how you want.

There are a few different approaches you can take to customizing your Refinery site‘s design:

  1. Install a pre-made theme. There‘s a collection of open source frontend themes for Refinery that you can install as a Rails engine. Find one you like, follow the install instructions, and voila!
  2. Tweak the default Refinery templates. Refinery makes it easy to override the default view templates to change the HTML structure. You can make small tweaks or completely rewrite the markup to fit your design.
  3. Use a CSS framework. If you want more control than a pre-made theme but don‘t want to start from scratch, using a CSS framework like Bootstrap or ZURB Foundation can be a good middle ground.

For this guide, we‘ll go with option #3 and use ZURB Foundation to build a custom blog theme. Foundation is a powerful, mobile-first CSS framework that provides a grid system, pre-built UI components, and handy JavaScript plugins.

Here‘s how to set up Foundation in your Refinery project and start customizing:

  1. Add the foundation-rails gem to your Gemfile and install it:
    gem ‘foundation-rails‘
    bundle install

  2. Import the Foundation CSS and JavaScript files in your assets:
    / In app/assets/stylesheets/application.css /
    *= require foundation_and_overrides

    / In app/assets/javascripts/application.js /
    //= require foundation
    $(document).foundation();

  3. Install the default Foundation layout and styles:
    rails g foundation:install

  4. Customize the Foundation settings and add your own styles:
    / In app/assets/stylesheets/foundation_and_overrides.scss /
    @import ‘settings‘;
    @import ‘foundation‘;

    / Add custom styles below /
    body { background: #f5f5f5; }
    / etc. /

With that, you‘ve got the full power of Foundation at your disposal! You can now use the grid system to structure your pages, customize the look and feel with Sass, and take advantage of pre-built components like dropdown menus, sliders, and modals.

From here, it‘s just a matter of overriding the default Refinery templates and writing your own CSS to build out your custom blog design. It may help to brush up on the Foundation docs to learn more about how the framework works.

Taking Your Blog Live: Deploying RefineryCMS

Once you‘ve got your blog looking good and working well locally, it‘s time to launch it and share it with the world!

Since RefineryCMS is a Rails app, your hosting options are the same as any other Rails application. Some popular choices are:

  • Heroku for easy, managed hosting
  • DigitalOcean, Linode, or Amazon EC2 if you prefer more control over your server
  • A VPS (Virtual Private Server) from a hosting company like Bluehost or MediaTemple

No matter which route you choose, deployment will generally involve the following steps:

  1. Create a production database and set your credentials
  2. Configure your web server to host your Rails app (Passenger + Nginx or Puma + Nginx are popular options)
  3. Precompile your assets
  4. Copy your app files to the server
  5. Set any required environment variables
  6. Run your database migrations
  7. Restart your web server

The exact details will vary based on your host, but they all provide guides for deploying Rails apps.

For a dead-simple deployment to get started, you can‘t beat Heroku. They have an official Refinery Heroku guide that makes it easy to deploy your blog with just a few commands.

RefineryCMS In The Wild

For some inspiration, let‘s take a quick look at a few examples of websites and blogs built with RefineryCMS:

As you can see, RefineryCMS is a good fit for everything from large corporate sites to documentation resources to SaaS products. With full control over both the frontend and backend, the customization possibilities are endless.

Learning More

We‘ve only just scratched the surface of what you can build with RefineryCMS. To continue your journey, here are some recommended resources for learning more:

I hope this guide has given you a solid foundation (pun intended) for building your own blog or content site with RefineryCMS. It‘s a powerful, flexible CMS that gives you the best of both worlds: an easy-to-use admin interface for content editors plus complete control over the code for us developers.

So go forth and build an awesome blog with RefineryCMS! And if you get stuck, don‘t hesitate to reach out to the Refinery community for help. Happy coding!

Similar Posts