Jekyll-Guide.md

Installation

You'll have to type some things in your command line. It's easier than it seems ;) Maybe you have some of the things already installed. To open your terminal: Applications -> Utilities -> Terminal

Install RubyGems

• Try gem in your command line. If you get gem: command not found, continue with next line. If you have already installed, go to Install Jekyll
• Download and extract: https://rubygems.org/pages/download
• From the terminal, go to the folder you just downloaded:

(in the command line what goes after the "#" is a comment and won't get executed; you as weel just don't have to paste/type it in the command line)

cd this will take you to your home directory

cd Downloads change directory to Downloads, the folder were the previous zip by default should have been downloaded to cd rubygems-2.5.1 # asuming you downloaded rubygems-2.5.1.zip, the latest rubygems zip

ruby setup.rb it will ask for your admin password

(more info: https://rubygems.org/pages/download)

Install Jekyll

gem install jekyll

(You may run into problems when running this. Its because you may lack other programs. Try looking here: http://jekyllrb.com/docs/troubleshooting/ or ping me)

A text editor

I recommend Sublime Text or VS Code

Workflow

Working with the repo, editing files, "uploading" changes

"Clone" repo (1 time step)

From your Web folder:

cd go to your User folder if you are not there

cd Web change directory to Web

git clone git@github.com:furilo/jekyll-test.git this will create a new folder "jekyll-test", and pull the code from the test repository

cd jekyll-test change directory to jekyll-test, your project folder

jekyll serve -w start jekyll

Go to http://127.0.0.1:4000/ - Voilá! You should see the site working. Its a simple blog with just one post. Click on the post title to go to the post: http://127.0.0.1:4000/jekyll/update/2016/01/29/welcome-to-jekyll.html

Editing files

Once you have your Sublime Text installed, just open your project folder with it. You should see something like:

For the time being, you just have to worry about one folder: _posts. If you open it, you will see one file (the only post that exists on the system right now). Click on it to open. You should see something like:

It's the only post we have, and it's the post you see when you go into http://127.0.0.1:4000/.

You will see a first block of lines enclosed in ---: this is the metadata of the post. You can guess a structure of

key: "Value"

in each line. And the names are pretty self-explanatory. Want to change the title? Give it a shot. Save the file, and go back to your browser. You should see the title of the post changed.

Once you have edited the file, its time to commit and push the changes to the repository, so everyone (including the production server once we are live) sees the changes (don't worry, we'll have a production and pre-production environment so you can test the changes in a real server before going into production)

Pull repo, commit and push changes

With Git we have a basic pull-edit-commit-push cycle:

• Pull the latest changes that have been done in the repo by other people. Everytime you start working in something, you should pull to check for any updates. If you don't pull and make changes, you may run into conflicts (they are solvable, but better try to avoid them).
• Edit your files (that includes adding new ones) with your text editor.
• Commit your changes: tell the repo you have made changes so it can keep track of them.
• Push your changes: once you have said you have changes, this changes should be uploaded (pushed) to the remote copy of the repo, so the rest of the people (and servers) can pull them and thus the cycle of collaboration flowing.

All these can be done with simple commands (all from your command line, from the folder where your project resides):

git pull to bring new changes to your local copy of the repo

git status it will show you if you have changes pending to be committed

git add . it will add all new files that you have created but are not yet committed in the repo]

git commit -m 'My recent changes' . it will commit your new changes from all files to the repo. You are including a message in the commit, that will be useful to the rest of the team to know what you are doing in your commit

git push push your commits to the repo

This way, when someone makes a git pull, the will receive the changes you just made.

(Once we are up and running with the project, we'll have a different folder structure, more files, more metadata fields... But the basics will be the same)