Using GitHub Pages in Visual Studio Code

Published: September 11, 2017   |   Read time:

Tagged:

I run this website using GitHub Pages, and I’ve used VSCode for a long time as a my main text editor, since it has a lot of really cool features. I wanted to make it easy to develop this site using VSCode, since the previous instructions for running the Jekyll/Ruby back-end for testing was … well, tedious … to say the least.

Here’s my setup guide for using VSCode to run a development server for GitHub pages in the background, to make writing and development easier.

Setup

This section follows a guide from Sverrir Sigmundarson1. It’s very clear, and if you want full details on installing everything you need for GitHub Pages from scratch, definitely go there. I’m just hitting the main point in this section, assuming you have the site, and just need things to run from VSCode.

I use Windows 10, so I wanted to follow JekyllRB’s instructions on this2; however, because VSCode Tasks run using the local system, we can’t do this via Bash on Ubuntu on Windows3. We need to install everything to the Windows machine.

Ruby and Ruby DevKit

Download Ruby and Ruby DevKit for Windows4.

Note Jekyll v3.x requires Ruby version >= 2.0.0. Select x32 or x64, depending on your system.

I picked Ruby v2.3.3, and Ruby DevKit for v2.0-v2.3. The DevKit is a self-extracting archive, so I put it in the same parent folder as where I installed Ruby.

Installing Ruby Installing Ruby DevKit

Initialize DevKit and bind it to Ruby installation

You can use the integrated terminal for this.

# since I installed it to D:, I need to run this first to switch to that drive
D:
cd Code\Ruby23-x64-DevKit

# Auto-detect Ruby installations and add them to a configuration file
ruby dk.rb init

# Ensure the init command completed successfully
ruby dk.rb review

# Bind DevKit to Ruby
ruby dk.rb install

Detecting Ruby -60%

Install necessary gems

Ruby uses gems to run, and GitHub Pages uses its own to do this. You can install them via

# install specific gems
gem install jekyll bundler wdm rouge

# OR

# install gems listed in your Gemfile
bundle install

Test the installation

To test everything installed correctly, open up the integrated terminal, and run:

bundle exec jekyll serve

It should look something like this, saying the site is being hosted.

Detecting Ruby -80%

Local hosting using VSCode Tasks

What we need

bundle exec jekyll serve is how we host the local version of the site as a background task. The site, by default, is hosted at 127.0.0.1:4000, which you’ll see when you run bundle exec jekyll serve for the first time.

Image of VSCode terminal -80%

Setting up a build task

Go to Tasks > Configure Tasks, and select the Other option. In the tasks.json file that opens, paste the following:

{
    "version": "2.0.0",
    "tasks": [{
        "taskName": "Serve development",
        "type": "shell",
        "command": "bundle",
        "args": [
            "exec",
            "jekyll",
            "serve",
            "--drafts"
        ],
        "group": {
            "kind": "build",
            "isDefault": true
        },
        "presentation": {
            "echo": true,
            "reveal": "always",
            "focus": false,
            "panel": "new"
        }
    }]
}

It should start running as if it was run from the Terminal, but now it’s easy to start and stop, just using Ctrl+Shift+B.

References & Footnotes