Jekyll and Github Pages
With this guide, you’re going to start with a computer connected to the Internet and end up with your own Jekyll-generated website hosted on Github Pages like this one!
Maintaining a website is free, educational, and fun. You’re in for a treat!
Step 1: Installation
I assume you’re using Windows. If you’re on a Mac, just replace Scoop with Homebrew.
-
Open your command prompt (
Windows key
, typecmd
,Enter
) and install Scoop –powershell Set-ExecutionPolicy RemoteSigned -scope CurrentUser powershell iex (new-object net.webclient).downloadstring('https://get.scoop.sh')
-
Use Scoop to install Git, Make, MSYS2, Ruby, and Wget, then configure Git.
scoop install git scoop bucket add versions extras scoop install make msys2 ruby27 wget git config --global user.name "Your Name" git config --global user.email "Your E-mail"
- Git is how you’ll push your website to Github Pages.
- Make lets you run makefiles, which simplify commands.
- MSYS2 helps with installing Ruby gems on Windows.
- Ruby is the language Jekyll is written in. You’ll use RubyGems to install Jekyll.
- Wget lets you download files from the Internet through the command prompt.
-
Close and re-open the command prompt, then install Jekyll.
gem install jekyll
-
In this tutorial, we’re going to use a makefile. Here’s what it contains –
g: git add --all . git commit -m "New website commit." git push origin master l: jekyll build jekyll serve --incremental --port 8000
When placed in the directory containing your website, this will enable two commands –
make g
will push your website to Github Pages for public view.make l
will run your website on your own computer at http://localhost:8000.
Step 2: Running Locally
Go ahead and browse through the large selection of themes at jekyllthemes.org, pick one you like, and navigate to its Github repo. (My favorite is DentistSmile.)
Clone your theme, enter the new directory, download the makefile, and serve!
git clone "https://github.com/gabrsar/dentistsmile"
cd dentistsmile
wget "http://danielmoore.us/jekyll-tutorial/makefile"
make l
Now visit http://localhost:8000. Voila!
If make l
failed, here’s a few trouble-shooting tips.
-
Google the error message and install any missing gems with
gem install <gem>
. -
Some Jekyll themes use Bundler, so if needed, run
gem install bundler
, thennotepad makefile
and edit tobundle exec jekyll serve --incremental --port 8000
. -
Run
notepad _config.yml
and add the lineexclude: [vendor]
.
Step 3: Going Public
Create and sign into a Github account.
Create new repository <your username>.github.io
, then return to your command prompt.
Remove the existing local repository, start a new one, point it to Github, and push to remote.
rmdir /s /q .git
git init
git remote add origin "https://github.com/<username>/<username>.github.io"
make g
Wait a minute, then visit <your username>.github.io
in a browser. Your website should be live! From now on, to update your public website, just run make g
.
(You can get Git to remember your Github credentials by running one of the commands here.)
Phew! That was a wild ride, but you now have your own website!
A few final tips –
-
You should develop for yourself locally by running
make l
and reservemake g
for when you want to make changes public. -
Jekyll uses Liquid and Markdown. Be familiar with both and read Jekyll’s documentation.
-
Get comfortable with a text editor. Visual Studio Code is popular. Consider learning Vim.
-
Jekyll was written by Tom Preston-Werner, the founder of Github. For a cool bit of history, check out his blog post announcing his invention.