BarcampGR 2017 Introduction to Jekyll

readme.md

BarcampGR 2017 Introduction to Jekyll

This is an introduction to using Jekyll and GitHub Pages as a static page generator to help people who aren't web devs, be web devs.

This guide is constructed assuming you are developing on a Windows based platform.

---

Assumptions.

1. You have some familiarity with the command line and command line tools.
2. You have some familiarity with git and GitHub.

Software requirements.

1. Ruby for Windows and Ruby DevKit.
2. Git for Windows.
3. Text editor (I prefer VSCode).

Ruby and Ruby DevKit installation steps.

1. Install Ruby by running the exe, using the default install options is fine.
2. Extract the Ruby DevKit (the exe is self extracting).
3. Edit the dk.rb so it will work with x64 installations.
   • add 'Software\Wow6432Node\RubyInstaller\MRI', to the enumerated registry keys (line 14) so x64 instances of Ruby can be found.
4. Initialize the Ruby DevKit installation.
   • ruby dk.rb init
5. Install the Ruby DevKit.
   • ruby dk.rb install
6. Install the Bundler and Jekyll gems.
   • gem install jekyll bundler
7. Instructions for configuring the git client can be found here.

Creating a website.

1. Create a GitHub repository.
   • Option A: Create a repository for your GitHub UserName root page IE https://dotps1.github.io.
     • Name the repository <GitHubUserName>.github.io.
     • All the source files can live in the master branch with this option.
   • Option B: Create a repository that would be a web path under your GitHub UserName root page IE https://dotps1.github.io/Jekyll.
     • Name the repository whatever you want the web path to be called, IE Jekyll.
     • Create a new branch in the repository called gh-pages.
2. Clone your repository.
   • git clone https://github.com/<GitHubUserName>/<GitHubUserName>.github.io or git clone https://github.com/<GitHubUserName>/<Repository>
3. Change directory into your cloned repository.
   • cd .\<Repository>
4. If you are doing option B from step 1, switch to the gh-pages branch.
   • git checkout gh-pages
5. Create your website.
   • jekyll new . --force
6. Edit the _config.yml.
   • code .\_config.yml
7. Build and run locally to see how its going!
   • bundle exec jekyll serve
   • Browse to the server address from the output in your shell, http://127.0.0.1:4000/Jekyll/.
8. Once your happy, push the site to GitHub!
   • git add .
   • git commit -a -m "Publishing my blog!"
   • git push