Portfolio Development with Github, Jekyll, & Yeoman/Gulpjs
Session 2 - V1.6
A Jekyll & gh-pages portfolio
Browser
Command Line
Editor
bash$ copy this.json that.json
//this is a comment
function (param) {
return foo;
}
Browser
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.6
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.6
Jekyll: The Big Picture
pages.html
_config.yml
templates
posts.md
images
Website.html
in _site directory
Works on github & on your machine!
v1.6
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.6
Portfolio Project Setup
Create a new repository called
[github username].github.io
(ignore setup page - we will do this in sec)
http://github.com/[github user name]
Create a new "blank" workspace called
portfolio & clone git@github.com:ricmclaughlin/jekyll-bootstrap-3.git
v1.6
Now let's save this portfolio progress to github.
In your portfolio workspace
# remove origin
git remote remove origin
# did it work?
git remote -v
# change the origin to YOUR github account
git remote add 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.6
That was totally easy. Let's fire it up and check it out!
What? It doesn't work?
# start up jekyll
jekyll serve
v1.6
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.6
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.6
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.6
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.6
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.6
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.6
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.6
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.6
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.6
So which version should I choose?
# you should be in the ~/workspace subdirectory
# tells rvm to use ruby 2.3
rvm use ruby-2.3
The latest 2.3 version is the best choice and you have it installed already! Just use it!
v1.6
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.6
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.6
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.6
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.6
# 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.6
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.6
Break Time!
Basic Blog Complete!!!
v1.6
Anatomy of a Github Portfolio
Project Detail Includes:
- What it does
- Technology Used
- Stuff You Learned
Projects by technology used - by tag
v1.6
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.6
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.6
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.6
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.6
# 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.6
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.6
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.6
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.6
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.6
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.6
First, let's send your latest stuff live!
git add .
git commit -m "new pages posts"
git push origin master
Cool!
v1.6
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.6
Session 2 Home Work
Make a blog post & tweet it to @ric_mclaughlin
v1.6
Portfolio Development with Github, Jekyll, & Yeoman/Gulpjs - Session 2 - V1.6
By Ric McLaughlin
Portfolio Development with Github, Jekyll, & Yeoman/Gulpjs - Session 2 - V1.6
From a static to a Jekyll generated portfolio
- 1,581