Github pages and relative paths
To rectify path discrepancies on GitHub Pages, implement root-relative URLs. Use this format: /repo-name/ when writing relative links. This will ensure your files are correctly linked.
Example for a repository named my-repo:
Update /repo-name/ to correspond to your exact repository name.
Jekyll: Your assistant for URL management
Given the dynamic nature of Jekyll, setting the baseurl in _config.yml to /project-name is crucial. When referencing assets, use {{ site.baseurl }} to ensure your paths don't get lost in the matrix, both locally and when deployed.
To serve locally with Jekyll:
This simulates the GitHub Pages environment, creating harmony between your local setup and the live site.
Let <base> tag lead the way
Add the <base> tag within the HTML <head> to maintain the correct paths:
Match this with {{ site.baseurl }} when working with Jekyll.
Troubleshooting GitHub Pages
Steer away from absolute paths; they can crack under pressure and lead to broken links on GitHub Pages. Break this pattern by meticulously organizing your directories — maintain a uniform folder structure for intuitive navigation.
Remember the rules of GitHub Pages caching: expect an up-to-15-minute window for changes to refresh.
Learning from others: Bootstrap and plugins
Take clues from existing frameworks. For example, Twitter Bootstrap structures links optimally for compatibility in any environment.
Consider the Jekyll Relative Links plugin. It adeptly converts relative links in Markdown files to persistent links.
Preview before launch
Always test your changes in a local environment (a necessary dress rehearsal). A local server is a truthful mirror — show your GitHub Pages site its reflection.
Fear not, your GitHub Pages can serve right from your master branch.
Was this article helpful?