Introduction to Jekyll

intro-to-jekyll.md

Jekyll

Static Websites and Blogs

COOL STUFF
Written in Ruby
Uses Markdown for content generation
Integrates with GitHub Pages

###What is Jekyll? Jekyll is a static site generator, written in Ruby. It renders static web pages from raw text/Markdown saved locally.

It was created by Tom Preston-Werner, co-founder of GitHub, and is

the engine behind GitHub Pages, a GitHub feature that allows users to host websites based on their GitHub repositories.

###Using Jekyll

1. Install Jekyll with gem install jekyll
2. Generate a Jekyll project with jekyll new project where project is the name of the site or blog being created
3. Change directories into the new project directory
4. Jekyll has a built in development server for previewing the rendered site jekyll serve
   • defaults to localhost:4000
   • --watch automatically reload the server when it detects changes to the project. NOTE: changes to _config.yml require a manual server restart (explanation)
   • --detach will run the server in a background process, effectively freeing up the terminal session for other use. To kill the server process use kill -9 PID where PID is the process ID of the Jekyll server. The process ID can be found with the top command or in the last line of console output from the server.

###Directory Structure

├── _config.yml
├── _drafts
|   ├── begin-with-the-crazy-ideas.md
|   └── on-simplicity-in-technology.md
├── _includes
|   ├── footer.html
|   └── header.html
├── _layouts
|   ├── default.html
|   └── post.html
├── _posts
|   ├── 2007-10-29-why-every-programmer-should-play-nethack.md
|   └── 2009-04-26-barcamp-boston-4-roundup.md
├── _data
|   └── members.yml
├── _site
└── index.html

###How It Works _config.yml (excerpt)

	# Site settings
	title: Amazing Blog
	email: [email protected]
	description: "Very Amazing Blog"
	baseurl: ""
	url: "http://amazingblog.com"

• SOME FUN YAML FACTS

  • YAML is a recursive acronym meaning "YAML Ain't Markup Language"
  • JSON is derived from YAML 1.2

• YAML is a "human readable data-serialization format". Key-value pairs defined within the Site settings in _config.yml are available throughout the site as variables - for example site.title returns "Amazing Blog" with the above configuration.

• The Liquid Templating Language is used to process templates. Variables within double-curly braces are evaluated and then rendered to the page - for example {{site.description}}

• Similar to Rails, Jekyll creates layouts that will be used to frame content on the site. Layouts are stored within _layouts. Partials are also used to DRY up pages. Partials are stored within _includes.

• Inside the _posts directory, individual Markdown files represent unique posts, or pages, of the site. Content is written as Markdown and rendered to HTML by Jeckyll when the site is "built"

• Filenames for posts must follow the specified format: YEAR-MONTH-DATE-title.md for example 2014-06-27-school-is-over.md.

• At the top of each post is a YAML Front-Matter block.

    ---
    layout: post
    title: Blogging Like a Hacker
    ---
  

Any file that contains a YAML front matter block will be processed by Jekyll as a special file. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines. This is also where predefined variables can be set, as in layout: post which specifies that the post.html layout will be used with this content. Custom variables defined here are accessed with Liquid tags on this page, or any page requires it.

• Syntax Highlighting - Jekyll has support for syntax highlighting using the Rouge gem.

    {% highlight ruby %}
    	def foo
    		puts 'foo'
    	end
    {% endhighlight %}
  

Surround code snippets with {% highlight %} and {% endhighlight %} tags and pass in a language, as above.

###Build A Site

1. Generate static version of the site with jekyll build
   • --destination <destination path> specifies directory for generator output
2. Change directories to destination path
3. Initialize new git repository, add files, and commit changes

###GitHub Pages

1. Create a new GitHub repository. When using GitHub pages, name of repository must be username.github.io where "username" is GitHub username
2. Add this repository as a remote of the local repository
3. Push changes
4. visit http://username.github.io to see your site
5. Pushing future commits to the remote repository will instantly update the site

##Resources

• Jekyll Documentation
• Markdown Syntax Documentation
• Using Jekyll With GitHub Pages