Corey Snyder

Just a blogging platform.

Getting Github Pages working with a bootstrap fork

I recently forked Bootstrap, made some changes, and then tried to setup Githug Pages to show off my newly modified CSS library.. It didn't go so well. Here's how it looked, and none of the links worked:
Broken Bootstrap

I googled around and didn't find anythign that solved all of my probllems.

"github pages loaded without css"

"github pages with bootstrap fork"

"github pages linking to other pages"

Here's how I eventually got it working...

Step 1 - Turn on github pages

a. Go to your repo on github and click the Settings tab.
b. Go to the Github Pages section and choose the "master branch /docs folder" from the Source dropdown.

Step 2- Checkout master

You need to make sure you make these changes in master as that is the branch Github is going to use for your pages. By default when you fork Bootstrap you may start in the v4-dev branch.

git checkout master  

Step 3 - Update your _config.yml

You'll need to modify or add the base_url property:

baseurl:          /bootstrap  

I set mine to /bootstrap because that's the repo url I've chosen. So my Github pages URL is

Step 4 - Update your CSS/JS references in /docs.

I replaced the references like:
<link href="../assets/css/docs.min.css" rel="stylesheet">
<link href="../../dist/css/bootstrap.min.css">

<link href="{{ site.baseurl }}/assets/css/docs.min.css" rel="stylesheet">

This changes how the files is referenced so back on github pages it used to reference the file like this:
And now it correclty appends the project to the URL:

Step 5 - Update your links in main.html

Open /docs/_includes/nav/main.html and change your links from:
<a href="../getting-started/">Getting started</a>
<a href="{{ site.baseurl}}/getting-started">Getting started</a>

Notice I remove the slash at the end of the URL. This must be done or the link wont work.

Step 6 - Profit.

Your bootstrap library documentation should look and function correctly.

comments powered by Disqus
Author Image

Corey Snyder

Front-End Engineer for Victoria's Secret. I have released multiple games to the AppStore, Windows 8, and Chrome Store. I play Ice Hockey a couple days a week and I love my Subaru WRX STI.