|
|
| Line 3: |
Line 3: |
| You, too, can have a glamorous GitHub page like mine! http://charlesreid1.github.io/ | | You, too, can have a glamorous GitHub page like mine! http://charlesreid1.github.io/ |
|
| |
|
| =Setting Up Octopress with GitHub Personal Page= | | =Setting Up Octopress with Github Personal Page= |
|
| |
|
| A user can create a repository to host static pages that are available at <code>http://username.github.io</code>. These pages can be set up to use [http://octopress.org/ Octopress], a slick blogging platform that uses [https://www.ruby-lang.org/en/ Ruby] and [http://jekyllrb.com/ Jekyll] underneath the hood.
| | You can create a repository that hosts static web content and is available at <code>http://username.github.io</code> - and you can use Octopress to deploy the static content from your markdown files. |
| | |
| You can create an Octopress blog that's available at <code>http://username.github.io</code>. Here's how I created mine.
| |
| | |
| First of all, I wanted to be able to blog with Octopress from my netbook or from my Macbook. I found a [http://blog.zerosharp.com/clone-your-octopress-to-blog-from-two-places/ fantastic guide] that described how to do this. I'll repeat my procedure here, again, mainly because this is all for my own notes, so I remember what I did.
| |
| | |
| ==Create Your Repo==
| |
| | |
| You first have to create a git repository with the name <code>username.github.io</code>. I'll just use my own username <code>charlesreid1</code> from this point on. Call me vain, but you know, these are just notes for myself anyway.
| |
| | |
| So now I have a repo named "charlesreid1.github.io".
| |
| | |
| What I'm gonna do is use some Ruby code (specifically, Octopress (and Jekyll, on top of which Octopress runs)) to dump out a bunch of CSS stylesheets and HTML files that contain a nice, pretty blog. All of the static content will have been generated from a pile of markdown files that contain a simple header and then a bunch of markdown text.
| |
| | |
| ==Get rbenv==
| |
| | |
| There are a lot of different versions of ruby out there. Various versions have various uses, but this leads to some version confusion. What we'll do is use a program called <nowiki>rbenv</nowiki> (ruby environment - get it?) to manage our ruby installation and its corresponding gems (gems are like ruby packages).
| |
| | |
| ===OS X===
| |
| | |
| To install this on OS X, I used Homebrew:
| |
| | |
| <pre>
| |
| brew update
| |
| brew install rbenv
| |
| brew install ruby-build
| |
| </pre>
| |
| | |
| ===Linux===
| |
| | |
| I wanted to install this on my [[Netbook]] running Ubuntu 12.04. I read that Ruby 1.9 had some serious flaws (just hearsay), so I'm using 2.0, specifically <code>ruby 2.0.0p247</code>. That means YOU CANNOT USE THE rbenv AND ruby-build IN THE APTITUDE REPOSITORIES!
| |
| | |
| You need the bleeding edge stuff. Here's how I installed that:
| |
| | |
| First, I installed [https://github.com/sstephenson/rbenv.git rbenv from sstephenson] on GitHub:
| |
| | |
| <pre>
| |
| git clone https://github.com/sstephenson/rbenv.git ~/.rbenv
| |
| echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
| |
| echo 'eval "$(rbenv init -)"' >> ~/.bashrc
| |
| </pre>
| |
| | |
| When you start a new shell, you should be able to type
| |
| | |
| <pre>
| |
| type rbenv
| |
| </pre>
| |
| | |
| and see:
| |
| | |
| <pre>
| |
| rbenv is a function
| |
| rbenv ()
| |
| {
| |
| [...]
| |
| </pre>
| |
| | |
| YAAAYYYY!!!
| |
| | |
| Next, install ruby-build from sstephenson,
| |
| | |
| <pre>
| |
| git clone https://github.com/sstephenson/ruby-build.git ~/.rbenv/plugins/ruby-build
| |
| </pre>
| |
| | |
| And now you should be able to use <code>ruby-build</code> to access various Ruby builds, which you can install and manage with <code>rbenv</code>.
| |
| | |
| ==Installing Ruby 2.0==
| |
| | |
| Now all that's left is to install Ruby 2.0 using <code>rbenv</code>:
| |
| | |
| <pre>
| |
| rbenv install 2.0.0-p247
| |
| </pre>
| |
| | |
| This will take a while. If it looks unresponsive, just pop open another tab and run "top". You'll see either the C compiler or a ruby process cranking away on the CPU until its done.
| |
| | |
| Once you've installed your version, you gotta pick which version is going to be your main ruby version.
| |
| | |
| First, see if there's already a ruby (maybe a system ruby? old crusty ruby? who knows):
| |
| | |
| <pre>
| |
| which ruby
| |
| ruby --version
| |
| </pre>
| |
| | |
| Who cares about that. Let's use our own damn <code>rbenv</code> Ruby!!!
| |
| | |
| Wait, what Ruby versions do we have?
| |
| | |
| <pre>
| |
| rbenv list
| |
| rbenv versions
| |
| </pre>
| |
| | |
| Oh, yeah, of course. Let's use Ruby <code>2.0.0-p247</code>, which should have been listed in the output of the command above:
| |
| | |
| <pre>
| |
| rbenv local 2.0.0-p247
| |
| </pre>
| |
| | |
| Now we have our correct version of Ruby (2.0.0-p247) set. Voila!
| |
| | |
| ==Getting the Octopress Gem Bundle==
| |
| | |
| The way Ruby works is, you create gems, which are a bit like Ruby apps, or plugins, or modules. These entities, whatever, these gems, they have general utility stuff like processing markdown or, you know, stuff, and like, stuff. I have no idea.
| |
| | |
| Anyway, which gems you need to install is project specific. That means your site will have some file that specifies which gems to install. BUT WHICH ONES? WHAT DO I DO???
| |
| | |
| Relax. That's what Octopress is for.
| |
| | |
| Octopress takes care of what gems to install and how to turn markdown into pretty web stuff. You just write the markdown.
| |
| | |
| ===Get Octopress===
| |
| | |
| Get Octopress here: https://github.com/imathis/octopress
| |
| | |
| Documentation for it here: http://octopress.org/
| |
| | |
| <pre>
| |
| git clone https://github.com/imathis/octopress.git octopress
| |
| </pre>
| |
| | |
| ===Install Gem Bundle===
| |
| | |
| You will first want to install the gem bundle that Octopress requires. So go to the Octopress repo and run:
| |
| | |
| <pre>
| |
| cd octopress
| |
| gem install bundler
| |
| </pre>
| |
| | |
| NOTE: If your system can't find "gem", you probably haven't picked your Ruby version correctly, or you have set up your initialization incorrectly.
| |
| | |
| This will install a bunch of gems that will now be available for Ruby. Note that these gems will be available EVERYWHERE. The reason they have to be run in this project folder is, out there in the wild there are lots of gems, but only a couple are needed by any given project. So for efficiency, each project keeps a list of which gems it needs. That's what the install command is doing.
| |
| | |
| ===Rehash rbenv===
| |
| | |
| Once you'e installed your gem bundle, you gotta rehash your rbenv:
| |
| | |
| <pre>
| |
| rbenv rehash
| |
| </pre>
| |
| | |
| ===Install the Bundle===
| |
| | |
| I dunno why you gotta run this extra step. Seems dumb to me. But just do it.
| |
| | |
| <pre>
| |
| bundle install
| |
| </pre>
| |
| | |
| ===The End Result===
| |
| | |
| Now what you have is a couple of utilities that allow you to deploy a copy of Octopress on Ruby in a Github repository. Then you can use Octopress to make/modify content, and when you're all done, run it through Octopress to make static pages that are then updated in the Github repository.
| |
| | |
| ==Still With Me?==
| |
| | |
| We're almost done.
| |
| | |
| ==Make Your Repo Into A Blog==
| |
| | |
| Next step is to use some of those handy-dandy utilities we just installed with the Octopress gem bundle to create a bunch of static blog content in our repository.
| |
| | |
| <pre>
| |
| cd charlesreid1.github.io/
| |
| bundle exec rake setup_github_pages
| |
| </pre>
| |
| | |
| NOTE: The <code>bundle exec rake</code> prefix is necessary because we want to make sure and use the rbenv-installed version of ruby, the same one that corresponds to the gem bundle we installed for Octopress. We do that by using <code>bundle exec rake</code> instead of just <code>rake</code>.
| |
| This will ask you for the address of your repository. This will allow you to deploy updated blog content using ruby.
| |
| | |
| Now if we want to make a post, we can use rake:
| |
| | |
| <pre>
| |
| bundle exec rake new_post['This is gonna be a great post!']
| |
| </pre>
| |
| | |
| Then it will tell you it made a markdown. Then you can edit the markdown to make a post:
| |
| | |
| <pre>
| |
| ---
| |
| layout: post
| |
| title: "This is gonna be a great post!"
| |
| date: 2014-04-07 18:38:21 -0700
| |
| comments: true
| |
| categories:
| |
| ---
| |
| | |
| ## It Works!
| |
| | |
| This post is definitely ready for some Markdown:
| |
| | |
| ```python
| |
| for i in range(10):
| |
| print i
| |
| ```
| |
| </pre>
| |
| | |
| ==Hosting Your Repo Blog Locally (Testing)==
| |
| | |
| (Add more here later)
| |
| | |
| ==Pushing Your Changes to Live Site==
| |
| | |
| You can push your changes to the live site using the following code:
| |
| | |
| <pre>
| |
| bundle exec rake generate
| |
| </pre>
| |
| | |
| This will turn all the markdown posts and other stuff you've modified into static content.
| |
| | |
| Next, you can (OPTIONALLY) update your site's "source code" branch:
| |
| | |
| <pre>
| |
| git add .
| |
| git commit -am "Updating site source branch"
| |
| git push origin source
| |
| </pre>
| |
| | |
| Finally, you can use a rake script that will take care of updating the master branch and pushing all your changes to the live GitHub site:
| |
| | |
| <pre>
| |
| bundle exec rake deploy
| |
| </pre>
| |
| | |
| This will push all the changes to _deploy, which is a copy of the master branch. The master branch is the branch that is served by the webserver when you visit http://charlesreid1.github.io
| |
| | |
| =Setting Up a Second Octopress with the Same Personal GitHub Page=
| |
| | |
| If you want to blog using Octopress in parallel, with two machines, then you can follow these instructions.
| |
| | |
| ==Preparing Your Second Octopress==
| |
| | |
| First, you can save yourself a lot of time by following all of the above instructions with respect to installing Ruby and the gem bundle for Octopress. This assumes that all of the rake commands provided by the Octopress gem bundle are available to you.
| |
| | |
| Okay, let's begin by cloning the repository for our site. BUT WAIT!!! Due to the way that our site was organized by our original call to <code>rake setup_github_pages</code> was to put the live site in the <code>master</code> branch, and the Octopress/Ruby stuff in the <code>source</code> branch. So let's make sure and check out the source branch:
| |
| | |
| <pre>
| |
| git clone -b source https://github.com/charlesreid1/charlesreid1.github.io.git charlesreid1.github.io/
| |
| </pre>
| |
| | |
| Now all of the static content was put (by the rake github pages command) into a folder called <code>_deploy</code>, which was made into the master branch. But because the name has an underscore in front, it is ignored by git. So let's explicitly check it out with Git. Remember the master branch is the default branch if we don't specify one:
| |
| | |
| <pre>
| |
| cd charlesreid1.github.io/
| |
| git clone https://github.com/charlesreid1/charlesreid1.github.io.git _deploy
| |
| </pre>
| |
| | |
| Now we can repeat some of the above commands in our fresh repo to generate content.
| |
| | |
| Everything up to this point was installation procedure.
| |
| | |
| ==Using Your Second Octopress==
| |
| | |
| Now you can run command like
| |
| | |
| <pre>
| |
| bundle exec rake new_post['This post is coming from another computer']
| |
| </pre>
| |
| | |
| and then modify the corresponding markdown file.
| |
| | |
| Once you're ready to deploy all the changes you've made, you just run the same commands as before. Optionally:
| |
| | |
| <pre>
| |
| git add .
| |
| git commit -am "Updating site source"
| |
| git push origin source
| |
| </pre>
| |
| | |
| and then deploy the changes made to the live site (the master branch) using rake deploy:
| |
| | |
| <pre>
| |
| bundle exec rake deploy
| |
| </pre>
| |
|
| |
|
| | This whole procedure gets a little lengthy, but my entire procedure is covered here: |
|
| |
|
| | [[Octopress/Octopress with Github Personal Pages]] |
|
| |
|
| =Setting Up Octopress with Github Project Pages= | | =Setting Up Octopress with Github Project Pages= |