Beginner's Guide

Beginner's Guide

We welcome contributions from all participants. If you'd like to contribute to this site and learn more about the technology involved, this is the place to start.

Step 1: Install Jekyll

Jekyll is a Ruby Gem that transforms text in various formats (HTML, Markdown, etc) into a static web page.

New to Ruby on Rails? Take a look at Michael Hartl's free RoR tutorial.

Start with the Official Jekyll installation instructions.

• If you're running Windows, there are specific instructions to Run Jekyll on Windows.

Dependencies - Jekyll requires certain code to be installed on your machine in order to run properly.

• Search for "install Jekyll (your operating system here)" for tutorials that include steps to get all the dependencies.
• Ruby
• RubyGems
• NodeJS or another Javascript runtime

Already have Ruby on Rails up and running?

• If you have RubyGems, just enter 'gem install jekyll' in your terminal
• Be sure to check that you have the dependencies installed first!

Step 2: Create your own branch

You'll need a GitHub account. New to GitHub? Check out a tutorial on getting started with GitHub.

• From the terminal, cd into the root of your GitHub directory and clone the repo: git clone https://github.com/code4lib/2016.code4lib.org.git

• Once the repo is there

  • cd 2016.code4lib.org
  • git pull

• Now that you've got a local copy of the code, you'll need to turn it into a live Rails app that will serve the page

  • bundle install -this installs all the gems Jekyll will need to run.
  • bundle exec jekyll serve -this starts a web server on your local machine so you can view the site locally

• Check out the site

  • Open a browser and go to localhost:4000
  • Now you need a branch for the issue you're working on. If you're working on an issue from the issues listed on GH, you can name it issue-3 (or whatever the number is). To do this:
    • git checkout -b issue-3
  • You now have a branch called 'issue-3'
  • If you're updating something other than an issue, give your branch a descriptive name like 'fix-broken-header'
  • Make sure you're on the new branch. git branch should show an asterisk next to the newly created branch.

Step 3: Make edits

• Some pages, like Speakers, pull data from _data/fileName.yml
• Look for footers and headers in the _includes directory
• Check http://localhost:4000 to see your changes

Step 4: Commit and submit pull request

1. git add {changed-files}
2. git commit -m "fixes issue #3" - add a message in the quotes to explain what the changes do
3. Add your branch to the remote git push --set-upstream origin issue-3 -replace 'issue-3' with the name of your branch git checkout master
4. In a browser go to https://github.com/code4lib/2016.code4lib.org
5. Make a pull request base:master and compare:issue-3, where issue-3 is your branch
6. Wait for someone to test your changes and merge
7. Do the dance of joy

---

To update the public site with any new changes:

1. make a pull request base:gh-pages and compare:master
2. Master should be up to date; you can merge your own pull request here.

Making changes to site CSS

Most of the base colors and fonts are set in Bootstrap 3.3.4's variables.less file located in prototype/bootstrap/less/. More info on compiling Bootstrap CSS with Grunt can be found on their Getting Started page. Other styles can be found in the css/main.css directory.

Resources

Technical Documentation from the Website Working Group.