Octopress: Difference between revisions

From charlesreid1
No edit summary
 
(16 intermediate revisions by the same user not shown)
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 Personal GitHub Page=
=Octopress Deploy Process=


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.
If you already have an Octopress set up (like me!), you can clone a copy on your second computer, and be ready to blog, by following these steps:


You can create an Octopress blog that's available at <code>http://username.github.io</code>. Here's how I created mine.
1. Clone your repository
 
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>
<pre>
brew update
git clone https://github.com/charlesreid1/charlesreid1.github.io
brew install rbenv
brew install ruby-build
</pre>
</pre>


===Linux===
2. Check out the source branch
 
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>
<pre>
git clone https://github.com/sstephenson/rbenv.git ~/.rbenv
cd charlesreid1.github.io/
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc
git checkout source
echo 'eval "$(rbenv init -)"' >> ~/.bashrc
cd ../
</pre>
</pre>


When you start a new shell, you should be able to type
3. Check out the deploy branch into <code>_deploy</code>:


<pre>
<pre>
type rbenv
cd charlesreid1.github.io/
</pre>
git clone https://github.com/charlesreid1/charlesreid1.github.io _deploy
 
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>
</pre>


Who cares about that. Let's use our own damn <code>rbenv</code> Ruby!!!
4. Make sure it is the master branch (i.e., the live changes you'll see on http://charlesreid1.github.io):
 
Wait, what Ruby versions do we have?


<pre>
<pre>
rbenv list
cd _deploy
rbenv versions
git checkout master
</pre>
</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:
5. Make new posts and things by running rake commands:


<pre>
<pre>
rbenv local 2.0.0-p247
bundle exec rake new_post['This is a new post title']
</pre>
</pre>


Now we have our correct version of Ruby (2.0.0-p247) set. Voila!
6. Commit your new posts to your source branch by running <code>git commit</code> on your newly-written blog posts.


==Getting the Octopress Gem Bundle==
=Setting Up Octopress with Github Personal Page=


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.
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.


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???
This whole procedure gets a little lengthy, but my entire procedure is covered here:


Relax. That's what Octopress is for.
[[Octopress/Octopress with Github Personal Pages]]


Octopress takes care of what gems to install and how to turn markdown into pretty web stuff. You just write the markdown.
=Setting Up Octopress with Github Project Pages=


===Get Octopress===
We saw above that Octopress enables you to set up an Octopress directory to work with a Github personal page repository.


Get Octopress here: https://github.com/imathis/octopress
But we may also want to set up Octopress for a project page repository - so that we can keep static web content relevant to the project that consists of a project blog and a set of project pages.


Documentation for it here: http://octopress.org/
[[Octopress/Octopress with Github Project Pages]]


<pre>
=Adding Non-Blog Content to Octopress=
git clone https://github.com/imathis/octopress.git octopress
</pre>


===Install Gem Bundle===
What if I wanna add an "about me" page? Then I can use the <code>rake new_page</code> command. See this page for details:


You will first want to install the gem bundle that Octopress requires. So go to the Octopress repo and run:
[[Octopress/Adding Non-Blog Content]]


<pre>
=Octopress Blogging Workflow with 2 Computers=
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 only reason they have to be run in this project folder is because there are a lot of gems, and only a couple are needed by any given project. So you only have the gems you need.
This is a description of my Octopress blogging workflow with 2 computers.


===Rehash rbenv===
[[Octopress/Octopress Workflow]]
 
Once you'e installed your gem bundle, you gotta rehash your rbenv:
 
<pre>
rbenv rehash
</pre>


===Install the Bundle===
=Modifying/Deleting Old Posts=


I dunno why you gotta run this extra step. Seems dumb to me. But just do it.
Sometimes, you accidentally post your password to your blog, and you gotta clean up after your mess. So how do you do that?


<pre>
Okay, this one is actually so easy that it doesn't even need its own page: you just modify or delete the markdown files.
bundle install
</pre>


===The End Result===
It's that simple.


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.
The next time you run <code>rake generate</code>, Octopress will be re-creating all the site's content from scratch, so no markdown files will be "missing" or "renamed". Octopress doesn't care who moved its cheese.


==Still With Me?==
=Octopress with Latex Math=


We're almost done.
Let's say you want to get Latex working with Octopress.


==Make Your Repo Into A Blog==
Bing! Done. Here you go.


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.
[[Octopress/Octopress with Latex]]


<pre>
=Octopress with iframes=
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>.
There's an Octopress plugin that allows you to embed iframe elements into an Octopress post using Liquid templates in your markdown.
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:
This allows you to do some really handy stuff, like embed D3, Spotify playlists, or Flickr slideshows into Octopress blogs.


<pre>
More info here: http://charlesreid1.github.io/blog/2014/04/11/octo-iframe/
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:
=Deploying Non-Blog Site with Octopress=


<pre>
One of the problems with the help that's available for Jekyll and Octopress is that just about everyone is using them for blogs. So if you want to make a page that's divided by sections and subsections (like a book or a report), then it's less clear how to use Octopress to manage your page. Sure, it's possible to hack Jeckyll to make it do something like that, But Octopress has such a nice workflow, I want to keep using Octopress for those kinds of pages/projects.
---
layout: post
title: "This is gonna be a great post!"
date: 2014-04-07 18:38:21 -0700
comments: true
categories:
---


## It Works!
This page covers my guide to setting up a non-blog Octopress site: [[Octopress/Non-blog Octopress Site]]


This post is definitely ready for some Markdown:
=Making Lists Look Badass=


```python
One of the biggest problems I have with Octopress/Jekyll/Markdown/Github pages is the way that bulleted and numbered lists look so awful.
for i in range(10):
    print i
```
</pre>


==Hosting Your Repo Blog Locally (Testing)==
Here, I describe how you can fix that and get some kick-ass list styles: [[Octopress/Lists]]


(Add more here later)
Finished product:


==Pushing Your Changes to Live Site==
[[Image:OctopressList.png|600px]]


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
[[Category:Octopress]]

Latest revision as of 06:17, 5 August 2014

Some notes on setting up Octopress to work with GitHub pages.

You, too, can have a glamorous GitHub page like mine! http://charlesreid1.github.io/

Octopress Deploy Process

If you already have an Octopress set up (like me!), you can clone a copy on your second computer, and be ready to blog, by following these steps:

1. Clone your repository 

git clone https://github.com/charlesreid1/charlesreid1.github.io

2. Check out the source branch 

cd charlesreid1.github.io/
git checkout source
cd ../

3. Check out the deploy branch into _deploy: 

cd charlesreid1.github.io/
git clone https://github.com/charlesreid1/charlesreid1.github.io _deploy

4. Make sure it is the master branch (i.e., the live changes you'll see on http://charlesreid1.github.io): 

cd _deploy
git checkout master

5. Make new posts and things by running rake commands: 

bundle exec rake new_post['This is a new post title']

6. Commit your new posts to your source branch by running git commit on your newly-written blog posts.

Setting Up Octopress with Github Personal Page

You can create a repository that hosts static web content and is available at http://username.github.io - and you can use Octopress to deploy the static content from your markdown files.

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

We saw above that Octopress enables you to set up an Octopress directory to work with a Github personal page repository.

But we may also want to set up Octopress for a project page repository - so that we can keep static web content relevant to the project that consists of a project blog and a set of project pages.

Octopress/Octopress with Github Project Pages

Adding Non-Blog Content to Octopress

What if I wanna add an "about me" page? Then I can use the rake new_page command. See this page for details:

Octopress/Adding Non-Blog Content

Octopress Blogging Workflow with 2 Computers

This is a description of my Octopress blogging workflow with 2 computers.

Octopress/Octopress Workflow

Modifying/Deleting Old Posts

Sometimes, you accidentally post your password to your blog, and you gotta clean up after your mess. So how do you do that?

Okay, this one is actually so easy that it doesn't even need its own page: you just modify or delete the markdown files.

It's that simple.

The next time you run rake generate, Octopress will be re-creating all the site's content from scratch, so no markdown files will be "missing" or "renamed". Octopress doesn't care who moved its cheese.

Octopress with Latex Math

Let's say you want to get Latex working with Octopress.

Bing! Done. Here you go.

Octopress/Octopress with Latex

Octopress with iframes

There's an Octopress plugin that allows you to embed iframe elements into an Octopress post using Liquid templates in your markdown.

This allows you to do some really handy stuff, like embed D3, Spotify playlists, or Flickr slideshows into Octopress blogs.

More info here: http://charlesreid1.github.io/blog/2014/04/11/octo-iframe/

Deploying Non-Blog Site with Octopress

One of the problems with the help that's available for Jekyll and Octopress is that just about everyone is using them for blogs. So if you want to make a page that's divided by sections and subsections (like a book or a report), then it's less clear how to use Octopress to manage your page. Sure, it's possible to hack Jeckyll to make it do something like that, But Octopress has such a nice workflow, I want to keep using Octopress for those kinds of pages/projects.

This page covers my guide to setting up a non-blog Octopress site: Octopress/Non-blog Octopress Site

Making Lists Look Badass

One of the biggest problems I have with Octopress/Jekyll/Markdown/Github pages is the way that bulleted and numbered lists look so awful.

Here, I describe how you can fix that and get some kick-ass list styles: Octopress/Lists

Finished product:

OctopressList.png

Retrieved from "https://charlesreid1.com/w/index.php?title=Octopress&oldid=5462"