alt text The Jekyll Website Method

Jekyll is a website builder, written in Ruby, that uses simple Markdown syntax within your text files to generate a static website.

A static website is something that is pre-rendered. All the files, (HTML, CSS, Javascript and images), exist “as is” and do not need to be processed on the server level.
Because they exist as is, they are generally significantly faster, and more stable than systems like WordPress.

Pros and Cons

Pros Cons
Speedy fast page load Can be complicated to set up for the not-so-tech
Security No CMS. No dashboard
Host your site anywhere Publishing the site requires tools & code on your PC
Fast content creation No WYSIWYG editor + image editor
Write offline Relatively few plugins for added functionality
Performance Relatively few themes
No maintenance Relatively small community

The decision to use Jekyll for this site was due to its quick method of turning a collection of text files into nicely formatted HTML with minimal effort or modification. Another benefit to using the Jekyll system, going forward, was to not hinder the free flow of thoughts as some systems do due to the necessity of using an often distracting online interface.

Set Up Your Jekyll Workspace

The following is meant to take some of the question and mystery out of your initial install and setup process; and of course, promote it forward in the spirit of open-source.

These steps have commands compatible for a PC utilizing the Linux operating system, specifically the widely used Ubuntu Linux distribution flavored Linux Mint. If you aren’t using Linux yet click these links and have a look. For the most part, Linux has all the functionality the average PC user needs.

  1. Install Linux on a PC if you haven’t already done so.

  2. Ensure some build tools are in place. Open up a terminal window to use the command prompt and paste the following 
    sudo apt-get install build-essential g++
  3. Install Ruby and another required development library 
    sudo apt-get install ruby-full
sudo apt-get install libz-dev
  4. Install Jekyll and the bundler using the Ruby gem method 
    sudo gem install jekyll
sudo gem install bundler

    Git Steps (optional)

    This site has been built locally without Git. If you want to use Git locally and/or are planning to use GitHub for version control and/or page hosting, steps 4 - 8 are what you likely want to do:

  5. Add a Git ppa. When software is not available in the default Ubuntu software list a good practice is to use a maintained ppa of that particular software repository. This ensures you will get regular updates when they’re released. A good site for finding ppa’s is launchpad.net 
    sudo add-apt-repository ppa:git-core/ppa
  6. Refresh your software library list and install Git 
    sudo apt update
sudo apt install git
  7. Configure your Git username and email address. This is not your GitHub username, but you could use your GitHub email address if you want 
    git config --global user.name "Your Name"
git config --global user.email "yourusername@users.noreply.github.com"
  8. Confirm the changes 
    git config --global user.name
git config --global user.email
  9. First Run - Initialize your new project. Change to your work folder where you want to create your project 
    cd /home/user/my_projects
git init name-of-new-project
cd name-of-new-project

    Start A Basic Site

    Here are the basic steps for starting a simple site so you can confirm Jekyll works:

  10. First Run - Start your new project. Change to your work folder where you want to create your project 
    cd /home/user/my_projects
mkdir name-of-new-project
cd name-of-new-project
  11. Create a Gemfile 
    nano Gemfile

    Copy and paste the following:

    gem 'github-pages'
source 'https://rubygems.org'
  12. Install some default Gems 
    bundle install
 (enter your password)

    To update the gems later on

    bundle update

    Launch Jekyll

    Once a project has been started you can launch Jekyll to preview your site.

  13. Launch Jekyll - Open a console and change to your project directory 
    cd /home/user/my_projects/name-of-new-project

    If you did the git method send the git init command

    git init

    Start Jekyll

    jekyll serve

    This command serves up the site and runs a “watch” on the contents of the project folder (the folder you’re in). Changes made to any files (except the configuration file!) will be auto-compiled into static HTML. Your site should now be browser viewable at url: localhost:4000.
    After you’ve tinkered on your site and got it the way you want it and are reasy to upload the files to the server, set your host url in _config.yml and issue the command:

    jekyll build

    Customize Your Site

    This site’s layout is based largely on a Jekyll theme by Michael Rose which is fairly involved and requires a considerable familiarity with the Jekyll system. Feel free to read through his Minimal Mistakes guide and see if his theme suits your needs.

If you aren’t ready to explore themes and are interested in a continuation of the steps for customizing your simple site you can find them at Make a static website with jekyll about a quarter of the way down the page in a section called Configuration.

Note: Here are a few other sites that were referenced for tutorial information:
Make a static website with jekyll
Setting up github pages locally with jekyll
John’s Cheatsheets - Jekyll

This Page In Jekyll Format

For those interested, here is what this page looks like in the Jekyll Markdown format:

---
title: "![alt text](/images/jekyll-logo.png) The Jekyll Website Method"
permalink: /howto/jekyll-website-intro/
excerpt: "How to setup a Jekyll work space."
modified: 2019-01-31T21:18:02-04:00
redirect_from:
  - /howto/
toc: true
toc_label: "On This Page"
toc_icon: "list"
---

[Jekyll](https://jekyllrb.com/) is a static site generator that runs on the [Ruby](https://www.ruby-lang.org/en/) programming language. A static website is pre-rendered: all the files (HTML, CSS, Javascript and images) exist as is, and do not need to be processed on the server level.<br />
Because they exist as is, they are generally significantly faster, and more stable than systems like WordPress.

## Pros and Cons

| Pros                    | Cons                                                   |
| ----------------------- | -----------------------------------------------------: |
| Speedy fast page load   | Can be complicated for non-programmers                 |
| Security                | No [CMS](https://en.wikipedia.org/wiki/Content_management_system). No dashboard |
| Host your site anywhere | Publishing the site requires tools & code on your PC   |
| Fast content creation   | No WYSIWYG editor + image editor                       |
| Write offline           | Relatively few plugins for added functionality         |
| Performance             | Relatively few themes                                  |
| No maintenance          | Relatively small community                             |

The decision to use Jekyll for this site was due to its quick method of turning a collection of text files into nicely formatted HTML with minimal effort and alteration. Another benefit to using the Jekyll system, going forward, was to not hinder the free flow of thoughts as some systems do due to the necessity of using an often distracting online interface.

## Set Up Your Jekyll Workspace

The following is meant to take some of the question and mystery out of your initial install and setup process; and of course, promote it forward in the spirit of [open-source](https://opensource.org/).  
  
These steps have commands compatible for a PC utilizing the [Linux](https://www.ted.com/talks/linus_torvalds_the_mind_behind_linux) operating system, specifically the widely used [Ubuntu](https://www.ubuntu.com/) Linux distribution flavored [Linux Mint](https://linuxmint.com/). 

1. Ensure some build tools are in place. Open up a terminal window to use the command prompt and paste the following
```bash
sudo apt-get install build-essential g++
```
2. Install Ruby and another required development library
```bash
sudo apt-get install ruby-full
sudo apt-get install libz-dev
```
3. Install Jekyll and the bundler using the Ruby gem method
```bash
sudo gem install jekyll
sudo gem install bundler
```
### Git Steps (optional)
- - -
This site has been built locally without Git. If you want to use Git locally and/or are planning to use GitHub for version control and/or page hosting, steps 4 - 8 are what you likely want to do:<br /> 
4. Add a Git ppa. When software is not available in the default Ubuntu software list a good practice is to use a maintained ppa of that particular software repository. This ensures you will get regular updates when they're released. A good site for finding ppa's is launchpad.net
```bash
sudo add-apt-repository ppa:git-core/ppa
```
5. Refresh your software library list and install Git
```bash
sudo apt update
sudo apt install git
```
6. Configure your Git username and email address. This is not your GitHub username, but you could use your GitHub email address if you want
```bash
git config --global user.name "Your Name"
git config --global user.email "yourusername@users.noreply.github.com"
```
7. Confirm the changes
```bash
git config --global user.name
git config --global user.email
```
8. First Run - Initialize your new project. Change to your work folder where you want to create your project 
```bash
cd /home/user/my_projects
git init name-of-new-project
cd name-of-new-project
```
- - -
## Start A Basic Site
Here are the basic steps for starting a simple site so you can confirm  Jekyll works: 
9. First Run - Start your new project. Change to your work folder where you want to create your project 
```bash
cd /home/user/my_projects
mkdir name-of-new-project
cd name-of-new-project
```
10. Create a Gemfile
```bash
nano Gemfile
```
Copy and paste the following:
```bash
gem 'github-pages'
source 'https://rubygems.org'
```
11. Install some default Gems
```bash
bundle install
 (enter your password)
```
To update the gems later on
```bash
bundle update
```
## Launch Jekyll
Once a project has been started you can launch Jekyll to preview your site. 
12. Launch Jekyll - Open a console and change to your project directory
```bash
cd /home/user/my_projects/name-of-new-project
```
If you did the git method send the git init command
```bash
git init
```
Start Jekyll
```bash
jekyll serve
```
This command serves up the site and runs a “watch” on the contents of the project folder (the folder you're in). Changes made to any files (except the configuration file!) will be auto-compiled into static HTML. Your site should now be browser viewable at url: [localhost:4000](http://localhost:4000).<br />
After you've tinkered on your site and got it the way you want it and are reasy to upload the files to the server, set your host url in _config.yml and issue the command:<br />
```bash
jekyll build
```

## Customize Your Site
This site's layout is based largely on a [Jekyll theme](http://jekyllthemes.org/) by [Michael Rose](https://mademistakes.com/about/) which is fairly involved and requires a considerable familiarity with the Jekyll system. Feel free to read through his [Minimal Mistakes](https://mmistakes.github.io/minimal-mistakes/) guide and see if his theme suits your needs.  
  
If you aren't ready to explore themes and are interested in a continuation of the steps for customizing your simple site you can find them at [Make a static website with jekyll](https://www.taniarascia.com/make-a-static-website-with-jekyll/) about a quarter of the way down the page in a section called **Configuration**.

**Note:** Here are a few other sites that were referenced for tutorial information:  
[Make a static website with jekyll](https://www.taniarascia.com/make-a-static-website-with-jekyll/)  
[Setting up github pages locally with jekyll](https://help.github.com/articles/setting-up-your-github-pages-site-locally-with-jekyll/)  
[John's Cheatsheets - Jekyll](http://john-cd.com/cheatsheets/Markup_and_Documentation/Jekyll/)
{: .notice--warning}

## This Page In Jekyll Format
For those interested, here is what this page looks like in Jekyll format:
```markdown
```