Build your GitHub Jekyll page locally
GitHub supports Jekyll as site generator and in most cases, this is good enough. Some more advanced pages may require additional Jekyll plugins that are not available on GitHub. In that case, the site must be built with a local Jekyll installation and pushed to the GitHub repository.
A personal home page can only be served from content in the master branch, therefore the master branch
must contain the output of Jekyll’s build command which normally goes to
_site. Everything else is
considered source code and has no business in the master branch. The separation into branches is
necessary, because some files will exist twice but with different contents. The
index.html in the
source root is very likely different from the
index.html in the compiled site.
The following applies to personal and organization home pages hosted on github.io. Project pages are a bit different and actually easier to setup, because the content for a project page can be served from a configurable branch.
We can leave intact the default directory structure with
_site as our build target and do the
- create the project.
- Add your remote origin, set configuration options. Like always for a new repository.
- create a
.nojekyllfile in the root directory. This tells GitHub to not build your site at all. It then assumes, all the content is submitted ready-to-be-served from the root of your repository.
- create a
_sitefolder and add it to
.gitignore(in the root)
- in the root folder of your project, create a new branch. I called mine
sourcebut it’s really up to you. The important thing is that
_sitemust not be part of your source branch (that’s why it goes to .gitignore) and must be on master, otherwise GitHub won’t serve the page.
git remote add origin firstname.lastname@example.org:username/username.github.io.git
git checkout -b master(switch to master, this step should be optional)
Now, begin adding content to the root directory. Commit and push this to the
source branch. Do a
jekyll build to build your site, thereafter go to the
_site directory, add, commit and push
everything to master.
Go to your GitHub repository and verify that everything is correct:
sourcebranch should contain all your source files, but no
masterbranch should contain the generated site and there shouldn’t be a
_sitefolder at all, because GitHub serves from the root directory, so everything that is in
_sitelocally (on your computer where you build it) must be in the root directory on GitHub. That’s why different branches are needed.
That should do it. You can now build your site locally and use every Jekyll plugin you want.