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 :)
Frequently Asked Questions about Octopress 3
What are the new features in Octopress 3?
Octopress 3 comes with a host of new features that make blog generation simpler and more efficient. The most significant change is the shift from a full-fledged blogging framework to a more modular Jekyll plugin system. This allows users to pick and choose the features they want, making the system more flexible and customizable. Other new features include a new command-line interface, improved deployment strategies, and better support for draft posts.
How does Octopress 3 compare to other blogging platforms?
Octopress 3 stands out from other blogging platforms due to its simplicity and flexibility. It is built on Jekyll, which means it inherits all the benefits of a static site generator, such as speed, security, and ease of use. Unlike other platforms, Octopress 3 allows you to write in Markdown, a simple and intuitive markup language. It also gives you full control over your site’s design and functionality, without the need for a database or server-side scripting.
How do I deploy my Octopress 3 blog to GitHub?
Deploying your Octopress 3 blog to GitHub is a straightforward process. First, you need to create a new repository on GitHub. Then, you can use the ‘octopress deploy’ command to push your site to this repository. Octopress 3 supports multiple deployment strategies, so you can choose the one that best suits your needs. For more detailed instructions, you can refer to the official Octopress documentation.
What hosting options are available for Octopress 3?
Octopress 3 can be hosted on any web server that supports static sites. This includes traditional web hosts, cloud storage services, and even GitHub Pages. Some popular options include A2 Hosting, which offers specialized Octopress hosting, and GitHub, which allows you to host your Octopress blog for free.
How do I contribute to the Octopress project?
The Octopress project is open source, which means anyone can contribute to its development. If you’re interested in contributing, you can start by checking out the project on GitHub. There, you can submit bug reports, propose new features, or even contribute code. Before contributing, make sure to read the project’s contribution guidelines.
How do I install Octopress 3?
Installing Octopress 3 is a simple process. First, you need to install Ruby and RubyGems, which are required to run Octopress. Then, you can install Octopress by running the command ‘gem install octopress’. Once Octopress is installed, you can create a new Octopress site by running the command ‘octopress new [site name]’.
How do I customize my Octopress 3 site?
Octopress 3 allows you to customize your site in many ways. You can choose from a variety of themes, or create your own. You can also customize your site’s layout, typography, and colors. All these customizations can be done through the site’s configuration file and the Sass stylesheets.
How do I update my Octopress 3 site?
Updating your Octopress 3 site is as simple as running the command ‘octopress update’. This will update your site’s content, layout, and styles. If you want to update Octopress itself, you can do so by running the command ‘gem update octopress’.
How do I migrate from Octopress 2 to Octopress 3?
Migrating from Octopress 2 to Octopress 3 requires some manual work, as the two versions are not directly compatible. However, the process is straightforward and well-documented in the official Octopress documentation. The main steps involve exporting your Octopress 2 content, creating a new Octopress 3 site, and importing your content into the new site.
What support options are available for Octopress 3?
As an open-source project, Octopress 3 is primarily supported by its community of users and developers. If you encounter any issues or have any questions, you can seek help on the Octopress GitHub page, or on various online forums and communities dedicated to Octopress and Jekyll.
Kingsley Silas is a web developer from Nigeria. He has a hunger for acquiring new knowledge in every aspect he finds interesting.