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 https://coreysnyder04.github.io/bootstrap/

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">


to:
<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:
https://coreysnyder04.github.io/dist/css/bootstrap.min.css

And now it correclty appends the project to the URL:
https://coreysnyder04.github.io/bootstrap/dist/css/bootstrap.min.css

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>

To:
<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.

Corey Snyder

Corey Snyder

Senior Front-End Engineer for Aver Inc.. I have independently developed & released multiple video-games. I play Ice Hockey, I race FPV Drones, and I love my Subaru WRX STI.

Read More