A smart and small starter kit for building a Jekyll website to host on Github Pages:
- Wiki-style editing workflow:
- Edit from the footer of every page.
- Create from the Page Not Found page. This allows wiki-style dangling-link page creation.
- Users' choice of editors: Prose or Github.
- Pre-configured for Prose:
- Browse/search pages when creating a link, via links.jsonp
- Browse/upload media from the post editor (
mediakey in _config.yml) - Sample metadata fields for post tagging etc.
- Bootstrap. Remove it if you like.
Quick start
- Fork this repo.
- Rename the fork to YOURNAME.github.io in project settings to enable Github Pages.
- Delete the CNAME file.
At this point your new site should be up!
To finish, go through _config.yml and customize the name, description, etc.
References
FAQs
Why are there two branches, master and gh-pages?
Github pages uses the master branch if you name your project YOURNAME.github.io. Otherwise, it uses the gh-pages branch, and serves your site at YOURNAME.github.io/PROJECTNAME. I keep both branches up to date so you can use it either way without creating a branch. After you fork, you can delete the unused branch to avoid confusion.
Why don't my edits show up immediately?
Github Pages caches pages for 10 minutes whenever they are accessed. If you make a change while the page is cached, you will still see the old page until the cached page expires.
To bypass the cache, add a "cache-busting" query string after the URL, like so:
`http://mysite.github.io/my-page?somerandomstring`.
How do I troubleshoot build failures?
If you have an error in one of your pages or templates, the new version will fail to build and Github will send you an email lacking any detail about what caused the failure.
To see the error you can run Jekyll locally on a workstation.
How can I enable SSL on Github Pages with a custom domain?
Front Github pages with a free Cloudflare account, as detailed in this article.
How can I pull in future improvements after I fork?
Probably the most reliable way is to manually copy any new bits you want. If you're comfortable with git merge or git cherry-pick, you can use these and then fix any merge conflicts by hand.
