Octopress 3 Arrives to Make Blog Generation Crazy Simple
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 :)