Octopress 3 Arrives to Make Blog Generation Crazy Simple

November 6, 2015

octopress

This article was peer reviewed by Fred Heath. Thanks to all of SitePoint’s peer reviewers for making SitePoint content the best it can be!

Octopress is an obsessively designed toolkit for writing and deploying Jekyll blogs. Pretty sweet, huh?
– Octopress

My joy has known no bounds since I came across Octopress, as creating a blog using it is incredibly easy. Things have gotten even more exciting with the announcement of Octopress 3. Octopress 3 includes features aimed at tackling the drawbacks of the previous versions. The newly-minted Octopress CLI allows you can create a new site, create new pages, add posts, and deploy with ease.

In this tutorial, we will create a simple blog, add a post and a page. Along the way, we will also see how to enable sharing to Twitter and deploy everything to Github.

Octopress Unveiling

First, install the Octopress gem. From your terminal:

gem install octopress

And with that, you have Octopress installed! I love Ruby and Rubygems!

Blog Creation

Getting up and running is easy with the new Octopress CLI commands. Navigate to your working directory and run the command below:

octopress new kinsomicrote

This will create a directory named kinsomicrote with scaffolding for the website. Replace “kinsomicrote” with whatever you want to call your blog. Navigate to the newly crewated directory and open up your text editor to see what you have. The files and folders should be in the tree format below:

cd kinsomicrote

→ tree
.
|____.gitignore
|_____includes
| |____head.html
| |____footer.html
| |____header.html
|____feed.xml
|_____sass
| |_____layout.scss
| |_____base.scss
| |_____syntax-highlighting.scss
|____css
| |____main.scss
|_____templates
| |____draft
| |____post
| |____page
|_____posts
| |____2015-10-15-welcome-to-jekyll.markdown
|____about.md
|____index.html
|_____layouts
| |____post.html
| |____default.html
| |____page.html
|_____config.yml

If you’ve every used Jekyll, it should look pretty similar.

Creating a Post

We can create a new post using one of the Octopress CLI commands:

octopress new post Welcome Aboard

This command creates a new blog post with the title Welcome Aboard. You can obviously use any title of your choice. The post is created in the _posts directory. When you open up this new post file in your text editor, it should be looking like what I have below:


---
layout: post
title: "Welcome Aboard"
date: 2015-10-15T09:31:09+01:00
---

By default, the post will be written as a markdown file. Your post content should go below the YAML front matter, which is what the content between the --- is called.

Front matter allows page-specific variables to be included at the top of a template using YAML or JSON. Front matter must come at the very top of the template and be separated from the rest of the content by a leading and trailing triple hyphen ---. Between these triple-dashed lines, you can set predefined and custom variables, such as Categories, Tags, and permalink. You can read more about front matter on Jekyll Documentation.

Viewing the Site

Before the site can be viewed it has to be built. Since Octopress is a wrapper around Jekyll, we will use the command below to build:

jekyll build

That will build a static HTML website that can be found in the _site directory. This is built out of the markdown files for pages, posts, stylesheets, and config.

To view the site run the command below from your terminal:

jekyll serve

Then, point your browser to the address localhost:4000.

Creating a New Page

Octopress comes with a default About page which is visible from your browser at http://localhost:4000/about/. The page can be found in the home directory of your site. When you generated the site using jekyll build, a folder was created for the about page. Navigate to _site/about directory and you will see the generated page.

There is an Octopress CLI command that can be used to create a new page similar to that used in creating a new post.

octopress new page contact.md

This will create a new page in the home directory of your application. The file created looks like:

---
layout: page
title: ""
---

Enter a title for the page, if you like.

You can enter contents for the page below the YAML front matter. Like in the case of the post, the contents are written in markdown format. You can also choose a path to create a page. For example:


octopress new page news/index.md

This will create a new directory called news and an index.md file inside it. When you run jekyll build or jekyll serve, an .html file is created just like you have for the “about” page we talked about. When the site is reloaded, the link for the page automatically shows up in the navigation bar.

Configuration

Octopress has a configuration file where you manage the settings for the website. This is the _config.yml file located in the home directory of the site. Here is an example of what it looks like:

# Site settings
title: Your awesome title
email: your-email@domain.com
description: > # this means to ignore newlines until "baseurl:"
  Write an awesome description for your new site here. You can edit this
  line in _config.yml. It will appear in your document head meta (for
  Google search results) and in your feed.xml site description.
baseurl: "" # the subpath of your site, e.g. /blog/
url: "http://yourdomain.com" # the base hostname & protocol for your site
twitter_username: jekyllrb
github_username:  jekyll

# Build settings
markdown: kramdown

From the configuration file, you can add your Twitter and Github usernames. They will show up at the bottom of your page, along with the description. Feel free to edit the settings as desired by adding the necessary information. You will have to restart your server for the configuration changes to show up in your browser. You can stop the server by pressing CTRL+C.

Social Media Sharing

Sharing your blog posts to social media like Twitter is important if you want to get a large audience. Fortunately, there is a gem available on Octopress to make that possible. For the purpose of this tutorial, we will focus on Twitter. You can check out the configuration for Facebook and Google Plus here.

Create a Gemfile in the home directory of your site. You can do so using your terminal, like so:

touch Gemfile

Add the following:

source 'https://rubygems.org'

group :jekyll_plugins do
  gem 'octopress-social'
end

And bundle install.

Open up _config.yml and add the following:

twitter:
  username:                               # Add your Twitter handle
  tweet_count:         false              # Show number of shares on Twitter
  size:                normal             # Or large
  embedded_link_color:                    # Set link color for embedded tweets

  follow_count:        false              # Show number of followers
  tweet_message:       ":title by :username :hashtags - :url" # With Tweet button Twitter add the URL last
  tweet_link_text:     Twitter            # Configure the link text
  tweet_link_title:    Share on Twitter   # Share link title
  profile_link_text:   Follow :username
  profile_link_title:  Follow :username on Twitter  # Profile link title text

Enter your Twitter username on the second line:

username: twitter_user

The other settings can be left as the default.

To use the Twitter share buttons, navigate to your site’s default layout and add this tag just below the closing tag.

{% twitter_script_tag %}

If you want the Twitter sharing button to display on every post, navigate to _layouts/post.html and add this underneath the content tag.

{% tweet_button %}

Do the same for pages if you want. Reload your browser to see the button.

There are other settings available, with you can check out at Octopress Social.

Deploying to GitHub Pages

We will be hosting our blog on GitHub. Create an account if you do not have one yet.

Create a new repository, give it a name in this format; username.github.io, replacing username with your Github username. Mine looks like this kinsomicrote.github.io.

Open up your terminal and initialize git. NOTE Replace username with your username on Github:


git init
git remote add origin https://github.com/username/username.github.io.git

Generate the deployment configuration file for our blog using octopress deploy init command.


octopress deploy init git git@github.com:user/project

This generates a file called _deploy.yml, which contains the deployment configuration:


method: git                               # How do you want to deploy? git, rsync or s3.
site_dir: _site                           # Location of your static site files.

git_url: git@github.com:kinsomicrote/kinsomicrote.github.io  # remote repository url, e.g. git@github.com:username/repo_name

# Note on git_branch:
# If using GitHub project pages, set the branch to 'gh-pages'.
# For GitHub user/organization pages or Heroku, set the branch to 'master'.
#
git_branch: master                        # Git branch where static site files are commited


# remote_path:                            # Destination directory

Now deploy!


octopress deploy

With that done, you site should be available! You can check out mine kinsomicrote.github.io (obviously, change the URL to your username).

Conclusion

Now you know how to setup a blog using Octopress 3. There are lots of exciting things Octopress 3 brings to the table. I encourage you to delve deeper into Octopress to discover them!

Thanks for staying with me till the end. Your feedback is welcome :)