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