Getting started with ruhoh (static blog)
Prerequisites: rvm, ruby, bundler
Check to see if you have
In the terminal try to switch to ruby version 1.9.3 by entering
rvm use 1.9.3.
If that succeeds you'll see a message like
which means you have
Then try entering
As long as you do not get a message similar to
command not found: bundle, then
bundler is installed.
Follow Installing Ruby on Ubuntu (and then come back)
if you think you need to install either
Notes for Experts
This tutorial is geared for both noobs and experts. For your convenience there are blocks of script without so much explanation or unneccessary commands.
Notes for Newbies
In this tutorial we're really cranking it to 11 so you can get a blog up quickly.
A brief synopsis is given here, but the steps will be explained as you go.
lsshow files (except dotfiles) in the specified (or current) directory
ls -ashow all files (including dotfiles)
bundle installinstalls ruby gems
bundle execruns a command from a ruby gem
git clonecopies a repository (meaning a database)
git addlets git know that a file should be committed in the next commit
git commit -m "blah blah"saves changes to the git repository
- You should always change the blah blah to something meaningful to you
git pushpushes commits to a remote repository (such as github)
pushdchanges into a directory
popdgoes back to the directory you were before you last did
mvrenames (or moves) a file or folder
rmremoves a file
rm -rremoves a folder
THE MOST IMPORTANT RULE for beginners: DON'T TYPE so much!.
Typing is the #1 reason for typos.
You're using a computer, which is created to decrease the number of things
a person has to remember to do.
After you type the first letter or two of a file or folder hit the
key a few times and it will either
fill out the name of the file for you
or give you a list of matching files
(or give you no list if you have a typo or the file doesn't exist yet)
It's almost impossible to have a typo if you're using
Don't type things out all the way unless you know you have to.
- dotfiles and dotfolders are hidden files and folders whose names begin with
- repository is a type of database that is used (mostly) for storing source files
- database generally refers to some sort of magic that stores information
- source file a easy-for-humans-to-read file format (that can be compiled)
- compiled file an easy-for-computers-to-read file format
- directory is a folder. The two words are interchangeable.
- folder is a directory.
Ruhoh is like Amish Friendship Bread
In order to host your blog on ruhoh.com you do, in fact, need to be using ruhoh (surprise!).
A ruhoh blog is a lot like Amish Friendship Bread, you get a little starter pack with all the indegridents you need and then you get to add stuff and grow it on your own.
The first thing you'll do is use
git to clone the "starter pack".
The "starter pack" is called blog-v2, meaning blog, version 2
(the second version of ruhoh).
For the Experts
Even though inuition tells you to rename
to something of your own choosing,
you can leave it for now (for copy-paste's sake)
and we'll change it later.
pushd ~ git clone 'git://github.com/ruhoh/blog.git' 'blog-v2' pushd blog-v2 git checkout "2.0.alpha" bundle install
For the Beginners
First go to your home directory which is something like
but is referred to as
~ for short.
Now double check that you are there (you'll see something similar to
/home/aj/, but with your name instead of mine (which is AJ).
Take a look in your directory to see what files and folders currently exist (it'll be stuff like Documents, Pictures, Movies, etc)
Now clone the starter pack into your home (which is where you are right now)
git clone 'git://github.com/ruhoh/blog.git' 'blog-v2'
Look again in your home and notice the new folder
Did you see it? Good. Look inside of it.
Now that you've see what's in it, change to that directory
(and note that the
./ prefix is optional, it's assumed by default,
so this time we'll leave it off)
Again, check where you are (it'll be something like
And again, look at the contents of the directory.
(again, leaving off the
., since it's optionall and assumed by default)
Before we go further I want you to notice something special about this
directory that was cloned from github. Run
but with the argument
-a you will see all files and folders,
including the hidden dotfiles and dotfolders
(the ones that begin with
. as the first character of their name).
You should notice that there is a folder
/ is used as a suffix to denote that the particular item is a
folder, not a file,
but it's okay if the
/ folder suffix is missing.
That said, it's best to always type the
/ folder suffix when entering commands
commands that only work on files will complain if they see a trailing
and you'll know immediately if you made a mistake.
The next step is to get the 2.0 branch of ruhoh. This will remove all of the committed (saved) files of the master branch (which are currently in the directory) and replace them with the files and folders of the 2.0.alpha branch.
git checkout "2.0.alpha"
All of the
git commands will only work in a git repository,
meaning a folder that has a hidden
.git/ folder in itself or a parent
(meaning that if
~/blog-v2/.git/ exists, I can also run git commands
~/blog-v2/themes/twitter/ because git will check in
~/blog-v2/themes/twitter/, fail, then check ~/blog-v2/themes/
, fail and finally succeed when checking~/blog-v2
). The exceptions to this rule aregit clone
(which creates a local copy of a repository) andgit init
(which adds the.git/` folder to the current directory).
If you try to run commands outside of a git repository, you'll get a message like
fatal: Not a git repository (or any of the parent directories): .git.
The last part in this step is to install ruhoh's ruby gems.
All of the
bundle only work in a ruby app -
meaning a folder that has a
otherwise you will get an error such as
Could not locate Gemfile.
So if you get that error, you're not in the right directory.
pwd to see where you are and
ls -a to check what files are there.
If you get the error
ERROR: Gem bundler is not installed, rungem install bundler
you should run
ruby --version then
rvm use default and then
(if the version of ruby changed, you may not have been using the correct version
of ruby at first).
After that do as it says and run
gem install bundler and, finally, try again.
Note: My instructions may become out of date, so check out http://ruhoh.com before you get too far along in this process.
Note: I put instructions on upgrading ruhoh in the appendix.
Feel empty inside - and feel great about it!
To run your blog in preview mode
bundle exec rackup -p 9292
rackup starts a webserver written in ruby.
The command will not "finish".
It will continue to run until killed.
(If it ran and then just quit, it wouldn't be very good at serving web pages)
Because of the configuration files that ruhoh created earlier, rackup knows how to dynamically compile the files of your blog on-the-fly.
Now open http://localhost:9292 and you should see next to nothing (an empty blog with a theme, but no posts). Hurrah!
Next go back to the terminal and
<ctrl>+c once or twice to quit
To compile your blog (production mode)
bundle exec ruhoh compile
I finally explain about
bundle exec in the appendix
And now you can serve the compiled version of your blog
with any static site server
(so if you have a server,
rsync -avhP it over and take a look).
pushd compiled/ python -m SimpleHTTPServer 3000
Python's SimpleHTTPServer module also runs a webserver, just like rackup, but it's written in python.
Because it doesn't read the configuration created by ruhoh,
python's webserver will just serve files from wherever
you start it.
In order to serve you blog,
you must start in from the
Now open http://localhost:3000 and you shouldn't at all be surprised by the near-nothingness in your view.
Go back to the terminal and
<ctrl>+c once or twice to kill python
so you can take a look at what you've created.
Other webservers might require you to move the
to a different location and or edit a configuration file that tells
it where files are located.
Anyway, now it's time to back out of the blog directory.
popd ls compiled popd ls blog-v2
As it turns out you could open this static site in a browser even without a server
On Mac OS X:
On Ubuntu Linux:
However, it probably won't look so pretty (it will be more just text) because without the server it can't find the additional files that tell the page what it should look like.
At this point it's important to note that the instructions for compiling your blog are slightly different based on how you intend to host it.
I host mine using the
blog subdomain of
Similarly, ruhoh will host your blog at
One day you may have your own server hosting your blog
and you might want to mount it at the pathname
In that case you'll need to
and make sure that
base_path is not commented and points
where you need it. For example:
Set vim to be your default editor
If you don't know what vim is, then you'll need to watch [vim for people who would rather not use vim][vim-docs] and then set your editor to be vim by running this command.
sudo update-alternatives –config editor
Select the first vim.
Publish your nothingness!
There's a reason I'm telling you to do this before you actually create a post is that there's a one-time setup process that I don't want to get confused with the posting process.
The name of your blog should be your github pages url.
My github name is coolaj86. Because my github name is coolaj86, my github repos url is automatically github.com/coolaj86. Also because my github name is coolaj86, my github pages url is automatically coolaj86.github.com.
The name of my blog should therefore be coolaj86.github.com.
For the love of all that is holy, DO NOT use username.github.com (change it to your github pages url).
Create a repository for yourself on github such as
* if you created it by the wrong name, you can rename it
- Copy the
https://url of the repo
* mine, for example, is https://github.com/coolaj86/coolaj86.github.com
Now for the work part.
mv ~/blog-v2/ ~/username.github.com/ pushd ~/username.github.com # Repositories are for source files, not compiled files rm -rf compiled/ # tell git to ignore "complied/" echo "compiled" >> .gitignore # tell git to ignore all lock files (such as Gemfile.lock) echo "*.lock" >> .gitignore # create a new branch called "blog" (we'll never go back 2.0.alpha) git checkout -b blog # The starter pack has the origin for ruhoh, which isn't for you git remote rename origin ruhoh # Your origin should be the repo you created earlier git remote add origin PASTE-YOUR-GITHUB-GIT-URL-HERE # take a look at all the things git status # add color, if you haven't already git config --global color.ui true git status # add everything new (this command should be used very rarely) git add . # see what changed git status git push origin -u blog
Note: If you can't figure out that PASTE-YOUR-GITHUB-GIT-URL-HERE was supposed to be replaced with the url you copied earlier you're either up too late, drunk, or you should just call it quits and move to learning something else because this is not your thing.
Your first post (and every post after it)
As exciting as it may be to show your friends that your blog is using the same twitter-bootstrap theme every blog uses these days, it would be a lot more exciting with some posts. Am I right or am I right?
This is how you create a blog post:
git checkout blog bundle exec ruhoh posts new "My First Post" vim posts/my-first-post.md
Write something explaining that you're starting a blog or copy an old post.
You should end up with a file that looks something like this:
--- title: "My First Post" date: "2013-02-14" categories: - raves --- Today is a good day. Here's the **proof**: * I'm alive and well. * I started my own static blog. * And then I found five dollars! What a *great* day!
It should be obvious that "My First Post" should be the title of your post and each post should therefore be different.
FYI: You can leave categories empty, but it's fun to have a few such as 'rants' (when you're complaining about something), 'raves' (when you're praising something), '42' (for ponderings about life, the universe, and everything), and 'boring' (for the super exciting stuff you don't want anyone to know about). These show up on the categories page of your blog.
If you'd like a quick markdown primer, see An introduction to Markdown
And once you've got your whatever going
git status git add posts/my-first-post.md git status git commit -m "added my first post"
At this point if you get a message about
git config and
git commit --amend,
you should follow those steps.
git status git push origin blog git status
Edit each of these for yourself (i.e. using
vim to open and edit the files).
If you're not sure what something means, it probably doesn't appy to you.
- the things that need to change here should be pretty obvious
- put in any text for the field
author(it's the title of the indented collection below it, not a field for you to put something)
config.yml(probably only needs a few things changed)
- production_url should be something like username.github.com
- I recommend that you change teh permalink to be /posts/:title/ because I often change the categories of my blog (and that ruins the idea of a permalink)
- sign up for a disqus account if you want to use this
- sign up for google analytics if you want to use this
Create a disqus account (takes about 15 seconds) and update the comments config.yml
Create a google analytics account (basically just linking it to your gmail account)
Season. Taste. Repeat.
After you've edited the files (assuming you're still in the ~/username.github.com folder):
You should see that at least
data.yml has changed.
Now you need to add and commit those files.
If you just type
git add (with a trailing space) and hit
<tab> a few times
you should see the list of files that you can add.
At the very least,
if you type the first few letters of the path of the file and hit
it will fill it out for you. For example:
git add config.yml git add widgets/comments/config.yml
And then commit the files.
git commit -m "updated configuration files"
Set up your Gravatar
- Go to http://gravatar.com
- Put in the same e-mail you use for github and click Get your Gravatar
- Follow the Instructions
Hosting with ruhoh
Continue with these instructions: Hosting ruhoh on Github Pages
not working yet, don't follow with these instructions
- Take a left and turn at post2.ruhoh.com
- Click on Authenticate with GitHub
- Authorize post2.ruhoh.com
- If you didn't get a gravatar you'll have an abnormally huge cat image that takes up way too much space... so go back and fix that.
- Name your blog whatever you want such as awesomeme.ruhoh.com
- click update
- click compile
- You may have to wait a bit, but eventually your blog will exist
I feel like there ought to be text between headers... even if it's just a meaningless self-reference.
If you dare to pull the latest updates to the ruhoh blogging software
bundle exec ruhoh xyz stuff) you can do so by executing
git fetch upstream git pull upstream "2.0.alpha" # NOTE: one day that will change to # git pull upstream "2.0.beta" # or probably maybe even straight to # git pull upstream "2.1"
However, if you're at all faint of heart, I'd recommend following the age-old adage of if it ain't broke, don't fix it until you have a particularly compelling reason to perform an upgrade.
In case you're wondering, the reason for all of this
bundle exec is to run little ruby apps that only exist in
the ruhoh-created directory.
This is advantageous because you can have not only different versions of ruhoh for each user on the computer, but also for each blog by that user. Since you probably don't have many blogs you could probably tell bundler to install ruhoh in your home directory... but I don't know how to do that.
Oh, and I'm blogging without internet at the moment, so I can't look it up.
By AJ ONeal
Did I make your day?
Buy me a coffee