Setting up Jekyll for GitHub Pages

in Software on Jekyll, Introductory

Using Bash for Windows

Install Bash

Notes for noobs:

Admin access in Linux aka Root Access

  • Open Bash from Admin CMD/PowerShell to have Root Access rights in Bash

How to navigate folders in bash.

Encountering Errno::EACCES

  • Make sure you ran Bash from an Admin CMD/PowerShell prompt
  • IF that still does not help then try using sudo in front of the command which is failing. More info…

Install Jekyll

Using Windows 10 Anniversary+
Jekyll Installation Instructions

Install missing GCC and Make

  • sudo apt-get install gcc
  • sudo apt-get install make

Installing Ruby

Install Ruby

  • apt-get seems to not install Ruby 2.0 so you’ll need to use rvm instead
  • After installing Ruby via rvm you will need to run source /home/[username]/.rvm/scripts/rvm each time you start bash. This is because the environment needs to load Ruby and Gems into CLI memory. To fix this you need to add the rvm scripts directory to the “bashrc” file.
    • Modify bashrc via nano nano ~/.bashrc (info)
    • Add the following to the end of the file: [[ -s "$HOME/.rvm/scripts/rvm" ]] && . "$HOME/.rvm/scripts/rvm" (info)
    • Exit with CTRL+X and enter y when prompted to save
    • Reload “bashrc” with the command source ~/.bashrc (info)
    • Commands for gem are now available when bash is started!

NOTE: You may see the error message “Unknown ruby interpreter version (do not know how to handle): RUBY_VERSION.” Based on this you can ignore this error.

Starting Jekyll

Helpful info about using Jekyll

I found that in Windows 10 Anniversary Update the file watcher fails so the command jekyll serve does not work. Instead I used jekyll serve --no-watch, but that comes at the cost of needing to stop the server, build, then start the server again each time I made a file change I wanted to see. Based on research this is a known issue that should be solved in Windows 10 Creators Update.

I also found that the default port 4000 was also occupied so I use the command jekyll serve --no-watch --port 9876 to force another unused port.

FIXED: Bash in Windows 10 Creators Update now correctly supports file watching so you can use the command jekyll serve --port 9876 without any issues!

Installing Gem “github-pages”

NOTE: I tried to get themes working first, but after adding this package the “minima” theme now works for posts locally so I suggest installing “github-pages” first, then worrying about themes.

Still not entirely sure why github-pages is required, needed, wanted, suggested… but I’m going ahead and installing it since that’s where I’m hosting my jekyll site.

  • Modify Gemfile
    • Remove/Comment: gem "jekyll", "3.4.3"
    • Add/Uncomment: gem "github-pages", group: :jekyll_plugins
  • Run gem install github-pages
    • This took a while, like more than 15 min…
    • NOTE: You can ignore the warning: “warning: insecure world writable dir in /home/username/.rvm/rubies/ruby-2.4.0/bin path, mode 04077 bash windows”. For more info.
  • Run bundle update
  • Run bundle install
    • Not sure if this is necessary after a bundle update

ISSUE: I got the following error: “jekyll 3.4.3 | Error: Could not find a JavaScript runtime. Seettps://github.com/rails/execjs for a list of available runtimes.”
SOLUTION: To fix this I followed the suggestion here to install nodejs, which I thought was already installed.

ISSUE: Next I got the following error: “Error: No repo name found. Specify using PAGES_REPO_NWO environment variables, ‘repository’ in your configuration, or set up an ‘origin’ git remote pointing to your github.com repository…”
SOLUTION: I found my solution in part here. I learned I needed a personal token from GitHub to access metadata. When I created my token I only applied read access to user info and user email. Then I used the token like suggested here like this: `JEKYLL_GITHUB_TOKEN=123abc [bundle exec] jekyll serve –port 9876’

ISSUE: Then I got the error: “Regenerating: 1 file(s) changed at 2017-06-03 16:08:06 …error: Error: No such file or directory - git”. From just a little reading here this apparently indicates git is not in the PATH or maybe not even installed at all.
SOLUTION: So I followed the “Installation” and “Configuration” steps in this article.

WOOT! NO MORE ERRORS!!!

Themes

In order to use a Jekyll theme on GitHub pages follow these instructions.
NOTE: I found that gem "theme-name" did not work for me, but gem install "theme-name" did work.

Themes don’t work for me…

I think I’m going to bail on themes for now. I cannot figure out how to get a theme to work. I tried to apply “jekyll-theme-minimal” and “jekyll-theme-midnight” but both epically failed. The index page content would not render at all after applying one of those themes. I’d like themes to work because “minima” is a bit boring, but there are more important things in life right now than styling my blog posts.

Themes Attempt 2

So I learned why my index.md file was not being rendered at all thanks to these two Stack Overflow questions: first, second. In the YAML the layout was set to home, but the themes I’ve been trying don’t have a home layout, only a default layout. Once I changed index.md to specify default it rendered! BUT, and it’s a HUGE BUT, the list of blog posts is no longer rendering. le sigh…

Themes Attempt 3+ (SPOILER: SUCCESS)

I visited Jekyll’s Themes Wiki on GitHub. After a lot of browsing I tried to get Bitwiser working. This is where the first glimpse of hope arrived. I added it manually which means editing the _config.yaml to not specify any theme (ex: #theme: comment-out-all-theme-declarations). This provided an implementation of index.html which I thought was interesting. Namely it looked like a template file. This is the key we’ll learn about later.

The Bitwiser theme was too buggy for me and did not format the list of posts on the home page well, so I decided to try the Hydejack theme. This theme encouraged an empty index.html. I thought that strange, but it started working right away. The home page, when set to layout: blog shows all posts as we see it today, and each post when set to layout: post is nicely formatted. I really like this theme. I had to add it manually as well even though there is a gem for it. The theme is not supported by GitHub pages via a gem. The Hydejack installation instructions have been very helpful in getting started and getting things configured.

The index.(html|md) Secret

Adapted from an email response from GitHub Support: The theme’s default layout, which you specified for index.md doesn’t have any code to show a list of posts, just the chosen page.

https://github.com/pages-themes/dinky/blob/master/_layouts/default.html

You might want to create a special layout for the home page which instead of the {{ content }} tag has something like this instead:

<ul>
  {% for post in site.posts %}
    <li>
      <a href=""></a>
    </li>
  {% endfor %}
</ul>

Which is described on Jekyll’s Wiki Page for Displaying an Index of Posts.

THANKS GITHUB SUPPORT!!!

Updating Hydejack (Manual Process)

I use the migration documentation to help with upgrades.

Interesting Reading

This article discusses 4 different static site generators. Not sure if I made the right choice, but in the end everything I have is in markdown which works with any of these options and more!

Site Up and Running

Finally, after weeks of struggling to get Jekyll up and running with GitHub Pages everything is up and running! I hope this post has helped you to navigate the insanity of getting Jekyll setup for your GitHub Pages site. If you have another awesome tutorial for the topic at hand please tweet it to me @dannydwarren! I’m always trying to learn and this was a fun, frustrating, and successful learning process.

© 2017. All rights reserved.

Powered by Hydejack v7.0.1