Git Hub Portfolio Development with Github, Jekyll, & Yeoman/Gulpjs

Session 2 - V1.5

                  From a static to a Jekyll generated portfolio

Browser

Command Line

Editor

bash$ copy this.json that.json
//this is a comment

function (param) {
    return foo;
}

Browser

What is a Retrospective?

  • You improve faster if you evaluate what worked and what didn't
  • For Projects, Tasks & Skills

v1.5

The Good

  • Easy Setup
  • Easy to Add Pages
  • No Server to Manage
  • Your other projects appear in your domain

Needs Improvement

Our Portfolio V1 - Retrospective

  • No Blog
  • No Portfolio (projects)
  • Difficult to grow
  • Hard to Manage

v1.5

oh. I need my portfolio site to be easy at first...

My buddy OctoJekyll 

told me all about this thingy called Jekyll from github that solves every problem I ever had.

Yeah!

v1.5

Jekyll: The Good Parts

Designed to solve the exact problem we have:

Host a blog without a server

Easily manage a large website

 

And it is free.

And it is github product.

v1.5

Jekyll: The Big Picture

pages.html

_config.yml

templates

posts.md

images

Website.html

in _site directory

Works on github & on your machine!

v1.5

Jekyll: Not as Good Parts

Out of the box Jekyll lacks:

  • Ability to create pages and posts easily
  • Bootstrap
  • Code highlighting
  • Permalinking

And a ton of other stuff you want...

But we have a plan...

v1.5

We can add a jekyll bootstrap starter project and start from there!

We just gotta clean out the old stuff so we can install the new!

Open your [github username].github.io workspace

# go up a directory 
cd ..

# remove your workspace directory
rm -rf workspace

# clone just the tip of the repo
git clone --depth 1 https://github.com/dbtek/jekyll-bootstrap-3 workspace

# go into your workspace directory
cd workspace

# change the origin to YOUR github account
git remote set-url origin http://github.com/[github username]/[github username].github.com.git

# did it work?
git remote -v

# now push your stuff
git push origin master  

v1.5

That was totally easy. Let's fire it up and check it out!

What? It doesn't work?

# start up jekyll

jekyll serve

v1.5

You need to install jekyll! And jekyll requires the ruby tool chain! You have work to do!

Yeah, yeah, I remember Octojekyll saying something about Ruby

And ah.. what's a tool chain?

v1.5

A tool chain

is a set of tools used to create a software product

So how big is this thing? We talking guppy? We talking whale?

v1.5

What's in a Ruby Tool Chain?

and what do we do with the tools?

Control Source Code

We need to:

Tool Type:

Version Control

Ruby Tool:

git

Run Code

Language Runtime

Ruby MRI

Manage Code Runner

Version Manager

rvm

Manage Dependencies

Package Manager

gem

Run Tasks over and over

Task Runner

rake

v1.5

OK. So I kinda remember that git saves stuff for us and gives us some sort of freedom.

And I know what Ruby is!! Jekyll runs on Ruby; but only certain versions. Which version do you have? 

Not sure... so I'll just install different ruby versions until it works!

v1.5

YOU SHALL NOT PASS!

Do not install ruby first. You must install RVM NOW else face the eternal hell of ruby version incompatibility, gem set chaos and general mayhem! 

v1.5

ah. ok. How do I get rvm? And what does it do again?

rvm helps us control which version of ruby and which versions of the gems (little packages of ruby code people have shared) we use in a project. It's like a ice cream.. 

???

oh, did I say that outloud? I meant it is like a simple way to specify and control your tool chain!

v1.5

Alright - how do you install it?

# you should be in the ~/workspace subdirectory

# this tells rvm to update itself

rvmsudo rvm get head

In your portfolio workspace

v1.5

How do I know it worked?

# you should be in the ~/workspace subdirectory

rvm reload # reload rvm after the install to make sure it is working correctly

rvm list # lists the rubies on your machine

v1.5

cool. Did rvm come with ruby too? 

# you should be in the ~/workspace subdirectory

# lists the ruby you could install

rvm list known 

nope. Remember rvm simply manages different versions of ruby; it isn't Ruby.

Checkout all the version you *could* install 

v1.5

So which version should I choose?

# you should be in the ~/workspace subdirectory

# tells rvm to use ruby 2.2.4

rvm use ruby-2.2.4    

The latest 2.2 version is the best choice and you have it installed already! Just use it!

 

v1.5

Is that it? You freaked out for just that??

# you should be in the ~/workspace subdirectory

rvm gemset create jekylldev # tells rvm to create a gemset called jekylldev

rvm gemset use jekylldev # tells rvm to use the jekylldev gemset

rvm gemset list # tell rvm to list the gemsets and show the one you are using

oh no. There is more. rvm helps you manage sharable chunks of code called gems into groups called a "gemset."  Jekyll is a gem so we need this part of rvm too. Let's make a gemset for our Jekyll development:

 

v1.5

This is taking a long time - can we just install jekyll now?

gem install jekyll          # tells gem, which is part of ruby, 
                            # to install the jekyll gem

yes, we can! 

 

v1.5

Can we look at it?

# tells jekyll to generate and serve up your website

jekyll serve --host $IP --port $PORT --baseurl '' 

Oh, yeah. Just type this in:

And click on the "Your code is running at: http://....." toast

v1.5

ok... that is a website... but there are ERROR in the terminal and the website isn't styled... How do I fix this? 

# before
ASSET_PATH : false

# after
ASSET_PATH : /assets/themes/bootstrap

In the c9 editor changes to your _config.yml:

# stops jekyll
ctrl-c

# tells jekyll to generate and serve up your website

jekyll serve --host $IP --port $PORT --baseurl '' 

v1.5

That is slick.

How do I change the title?

# before
title : Jekyll Bootstrap-3 # change this to:


# after
title : My Blog # New Blog title!

In the c9 editor open up _config.yml and change: 

And refresh your preview tab in your browser...

v1.5

That didn't

work.

Why?

# stops jekyll
ctrl-c

# tells jekyll to generate and serve up your website

jekyll serve --host $IP --port $PORT --baseurl '' 

Jekyll does not rebuild and reload after a change to _config.yml

BUT will rebuild and reload on page or other asset changes!

Restart Jekyll to see your title change

v1.5

Now how do I add a post?

# before
permalink: /:categories/:year/:month/:day/:title
production_url : http://username.github.io

# after
permalink: /:categories/:title
production_url : http://[Your USERNAME].github.io

We can do that! But first let's change the way jekyll creates URLs in your site. Make these changes to your _config.yml:

v1.5

# before

title : Jekyll Bootstrap-3
tagline: Site Tagline
author :
  name : Name Lastname
  email : blah@email.test
  github : username
  twitter : username
  feedburner : feedname

# after
title : [your blog title]
tagline: [your blog tagline]
author :
  name : [your name]
  email : [your email]
  github : [your github]
  twitter : [your blog twitter]
  feedburner : [your feedburner]

Now complete the personalization surgery on your _config.yml:

Now restart jekyll

And click on the "Your code is running at: http://....." toast

v1.5

Jeesh. Can we just add a post now????

Yes! First, make another terminal window then type in this command:

rake post title="My First Post"      # tells rake, a task runner for ruby, 
                                     # to make a new page titled "My First Post"

Now refresh your preview tab in your browser

v1.5

Break Time!

Basic Blog Complete!!!

v1.5

Anatomy of a Github Portfolio

Project Detail Includes:

  • What it does
  • Technology Used
  • Stuff You Learned

Projects by technology used - by tag

v1.5

That was easy but aren't we making an HTML website???  Why is file extension .md? 

Excellent questions - .md stands for markdown. It's easier to write than HTML, which lots of folks call "mark up" - get it??

Jekyll converts our .md file into a .html file. Let's talk markdown a sec...

v1.5

Here is a little markdown cheat sheet!

 Now let's add some markdown to our "my-first-post.md" file!

Markdown HTML
# Yeah! <h1>Yeah!</h1>
## Super! <h2>Super!</h2>
*sure* <i>sure</i>
[google homepage](https://www.google.com) <a href="https://www.google.com">google homepage</a>
`source` <code>source</code>

v1.5

Now refresh your browser preview tab

# before ##################
---
layout: post
title: "My First Post"
description: ""
category: 
tags: []
---
{% include JB/setup %}

# after ###################
---
layout: post
title: "My First Post"
description: ""
category:
tags: []
---
{% include JB/setup %}

# I love jekyll!

## Oh, yes I do!

### isn't it fun

#### how 'bout you?

In the "my-first-post.md" file:

v1.5

I see! Now I can jam out blog posts!

What is all that stuff at the top of the .md file? What's that for?

---
layout: post
title: "My First Post"
description: ""
category:
tags: []
---

This stuff??

Yep, that stuff.

That is called the "front matter." That tells Jekyll how to name and sort your stuff. 

v1.5

# before ##################
---
layout: post
title: "My First Post"
description: ""
category:
tags: []
---

# after ##################
---
layout: post
title: "My First Post"
description: ""
category: posts
tags: [jekyll, love]
---

# I love jekyll!
## Oh, yes I do!
### it's so fun
#### how 'bout you?

Seeing that we want "posts" and "projects" in our portfolio, let's change the category to "posts" and add "jekyll" and "love" to the tags array.  

in the "my-first-post.md" file:

Now refresh your browser preview tab and look at the Tags page

v1.5

Sweet Success! Let's add a "project" and a list of projects to the website now, ok?

It looks like jekyll used our tags from the front matter to sort "My First Post" in the "love" section and the "jekyll" section!!

Yes it did!!

Sure thing!

v1.5

Let's make a new project post from the command line:

rake post title="My First Project"  # tells rake, a task runner for ruby, 
                                    # to make a new post titled "My First Project"
# before ##################
---
layout: post
title: "My First Project"
description: ""
category: 
tags: []
---
{% include JB/setup %}

# after ##################
---
layout: post
title: "My First Project"
description: ""
category: projects
tags: [html, css]
---
{% include JB/setup %}

# My First Project!!

in the "my-first-project.md" file change the category and tags and add a little markdown

Check it out: refresh your browser and nav to Categories page

v1.5

This is excellent!! We made a project category.

Can we add a page that shows just projects?

You are on fire! We can do that!!

Now refresh your preview tab and access the projects-list.html page

rake page name="projects-list.html"   # tells rake, a task runner for ruby 
                                      # to make a new page titled "projects-list"

v1.5

Disappointed! Where is the projects page?

# before ##################
---
layout: page
title: "Projects"
description: ""
---
{% include JB/setup %}

# after ##################
---
layout: page
title: "Projects"
description: ""
group: navigation
---
{% include JB/setup %}

{% assign posts_collate = site.categories.projects %}
{% include JB/posts_collate %}

duh. Forgot. We need to add a little special sauce to the projects-list.html file!

v1.5

Bam! A list of projects!!

Hum, let's think on this a bit.

Let's keep going! I am the king of the world! I can do anything!

v1.5

First, let's send your latest stuff live!

git add .
git commit -m "new pages posts"
git push origin master  

Cool!

v1.5

True. But you know the basics. 

Nope, I think that's it. We are done - for today.

WTF? It isn't done. My portfolio isn't done!

You can make pages and posts. You can make a project list page so you can make a posts list page. You know how to add things to the nav bar. So yeah, the rest is up to you!

v1.5

Session 2 Home Work

Make a blog post & tweet it to @ric_mclaughlin  

v1.5

Portfolio Development with Github, Jekyll, & Yeoman/Gulpjs - Session 2 - V1.5

By Ric McLaughlin

Portfolio Development with Github, Jekyll, & Yeoman/Gulpjs - Session 2 - V1.5

From a static to a Jekyll generated portfolio

  • 1,279