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.
-
Install Linux on a PC if you haven’t already done so.
- 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++
- Install Ruby and another required development library
sudo apt-get install ruby-full sudo apt-get install libz-dev
- 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:
- 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
- Refresh your software library list and install Git
sudo apt update sudo apt install git
- 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"
- Confirm the changes
git config --global user.name git config --global user.email
- 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:
- 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
- Create a Gemfile
nano Gemfile
Copy and paste the following:
gem 'github-pages' source 'https://rubygems.org'
- 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.
- 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: " 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
```