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.

  1. Open your command prompt (Windows key, type cmd, Enter) and install Scoop

     powershell Set-ExecutionPolicy RemoteSigned -scope CurrentUser
     powershell iex (new-object net.webclient).downloadstring('https://get.scoop.sh')
    
  2. 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.
  3. Close and re-open the command prompt, then install Jekyll.

     gem install jekyll
    
  4. 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.

  1. Google the error message and install any missing gems with gem install <gem>.

  2. Some Jekyll themes use Bundler, so if needed, run gem install bundler, then notepad makefile and edit to bundle exec jekyll serve --incremental --port 8000.

  3. Run notepad _config.yml and add the line exclude: [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 reserve make 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.