Jekyll learning note

November 22, 2014

Reading time ~13 minutes

配置

Drafts: –drafts

Getting Started

Ouick-start guide

install and get a boilerplate

    ~ $ gem install jekyll
	// to install in this directory instead of a new directory name
	// jekyll new .
	~ $ jekyll new myblog
	~ $ cd myblog
	~/myblog $ jekyll se

Directory structure

	|_config.yml
	|_drafts
	|    begin-with-the-crazy-ideas.textile
	|    on-simplicity-in-technology.markdown
	|_includes
	|    footer.html
	|    header.html
	|_layouts
	|    default.html
	|    post.html
	|_posts
	|    2007-10-29-why-every-programmer-should-play-nethack.textile
	|    2009-04-26-barcamp-boston-4-roundup.textile
	|_data
	|    members.yml
	|_site
		 index.html
  • _config.yml
    • Stores configuration data.Many of these options can be specified from the command line executable but it’s easier to specify them here so you don’t have to remember them.
  • _drafts
    • unpublished posts.The format of thes files is without a date: title.MARKUP
  • _includes
    • These are partials than can be mixed and matched by your layouts and posts to facilitate reuse. The liquid tag <pre>{\% include file.ext \%}</pre> can be used to include the partial in _includes/file.ext
  • _layouts
    • These are the templates that wrap posts. Layouts are chosen on a post-by-post basic in the YAML Front Matter. The liquid tag is used to inject content into the web page.
  • _posts
    • content. The naming convention of these files is important, and must follow the format: YEAR-MONTH-DAY-title.MARKUP.
  • _data
    • Well-formatted site data should be placed here(ends up with .yml or .yaml). you can access members.yml under this directory through site.data.memebers.
  • _site
    • This is where the generated site will be placed(by default) once Jekyll is done transforming it. It’s probably a good idea to add this to your .gitignore file.
  • index.html(and other HTML, Markdown, Textile files)
    • Provided that the file has a YAML Front Matter section, it will be transformedby Jekyll.
  • Other Files/Folders
    • Every other directory and files except for those listed above–Such as css and images folders, favicon.ico files, and so forth–will be copied verbatim to the generated site.

Configuration

Global Configuration

// look up from the documation , do not list here

  • Site Source

  • Change the directory where Jekyll will read files

Front Matter defaults

Specify site-wide defaults using the defaults key in the _config.yml file.

The defaults key holds an array of scope/values pairs that define what defaults should be set for a particular file path, and optionally, a file type in that path.

e.g. add a default layout to all pages and posts in your site. add this below to your _config.yml file:

    defaults:
	  -
	    scope:
		  path: "" #an empty string here means all files in the project.
	    values:
		  layout: "default"

If you don’t want to set a layout on every file in your project-like css files,for example-so you can also specify a type value under the scope key.

    defaults:
	  -
	    scope:
		  path: ""
		  type: "posts"
	  -
	    values:
		  layout: "default"

The different type that are available to you are pages, posts, drafts or any collection in your site.

you can set multiyle scope/values pairs for defaults.

    defaults:
	  -
	    scope:
		  path: ""
		  type: "posts"
	    values:
		  layout: "my-site"
	  -
	    scope:
		  path: "projects"
		  type: "pages"
	    values:
		  layout: "project" # overrides previous default layout
		  author: "Mr. Example"


    collection:
	  - my_collection:
	    output: true

	defaults:
	  -
	    scope:
		  path: ""
		  type: "my_collection" # a collection in your site, in plural form
	    values:
		  layout: "default"

In this example the layout is set to default inside the collection with the name my_collection.

Precedence###

You can override settings from other scope/values pair by specifying a more specific path for the scope.

You set defaults in the site configuration by adding a defaults section to your _config.yml file, you can override those settings in a post or page file. All you need to do is specify the setting in the post or page front matter. For example:

    #In _config.yml
	...
	defaults:
	  -
	    scope:
		  path: "projects"
		  type: "pages"
	    values:
		  layout: "project"
		  author: "Mr. Example"
		  category: "project"
	...



    #In projects/foo_project.md
	---
	author: "Jack Example"
	layout: "foobar"
	---
	The post text goes here...

The projects/foo_project.md would have the layout set to foobar instead of project and the author set to Jack Example istead of Mr. Example when the site is built.

Default Configuration

    #Where things are
	source:      .
	destination: ./_site
	plugins:     ./_plugins
	layouts:     ./_layouts
	data_source: ./_data
	collection:  null


	#Handling Reading
	safe:          false
	include:       [".htacess"]
	exclude:       []
	keep_files:    [".git", ".svn"]
	encoding:      "utf-8"
	markdown_ext:  "markdown,mkdown,mkdn,mkd,md"
	textile_ext    "textile"

	# Filtering Content
	show_darfts: null
	limit_posts: 0
	future: true
	unplished: false

	#Plugins
	whitelist: []
	gems:      []

	#Conversion
	markdown:    kramdown
	highlighter: pygments
	lsi:         false
	excerpt_separator: "\n\n"

	#Serving
	detach: false
	port:   4000
	host:   0.0.0.0
	baseurl: "" #does not include hostn

	#Backwards-compatibility
	relative_permalinks: false

	#Outputting
	permalink:     date
	paginate_path: /page:num
	timezone:      null

	quiet:    false
	defaults: []

	#Markdown Processors
	maruku:
	  use_tex:    false
	  use_divs:   false
	  png_engine: blahtex
	  png_dir:    images/latex
	  png_url:    /images/latex
	  fenced_code_blocks: true

	rdiscount:
	  extensions: []

	redcarpet:
	  extensions: []

	kramdown:
	  auto_ids:      true
	  footernote_nr: 1
	  entity_output: as_char
	  toc_levels:    1..6
	  smart_quotes:  lsquo,rsquo,ldquo,rdquo
	  use_coderay:   false

	  coderay:
	    coderay_wrap:              div
		coderay_line_numbers:      inline
		coderay_line_number_start: 1
		coderay_tab_width:         4
		coderay_bold_every:        10
		coderay_css:               style

	redcloth:
	  hard_breaks: true

Markdown Options

Redcarpet

Redcarpet can be configured by providing an extensions sub-setting, whose value should be an array of strings. Each string should be an array of strings. Each string should be the name of one of the Redcarpet::Markdown class’s extensions; if present in the array, it will set the corresponding extension to true.

two sepcial Redcarpet extensions:

  • no_fenced_code_blocks – By default, Jekyll sets the fenced_code_blocks extension(for delimiting code blocks with triple tidles(~) or triple backticks(`)) to true, probably because Github’s eager adoption of them is starting to make them inescapable. Redcarpet’s narmal fenced_code_blocks extension is inert when used with Jexyll; instead, you can use this inverted version of extension for disabling fenced code.

Note that you can also specify a language for highlighting after the first delimiter:

    ```ruby
	# ... ruby code
	```

With both fenced code blocks and highlighter enabled, this will statically highlight the code; without any syntax highlighter, it will add a class=”LANGUAGE” attribute to the element, which can be used as a hint by various JavaScript code highlighting libraries.

  • smart–This psoudo-extension turns on SmartyPants, which converts straight quetes to curly quotes and runs of hyphens to em(—) and en(–) dashes.

All other extensions retain their usual names from Redcarpet, and no renderer options aside from smart can be specified in Jekyll.A list of availabel extensions can be found in the Redcarpet README file.(look the right version of Redcarpet:) Jeyll currently uses v2.2x, and extensions like footnotes and highlight weren’t added until after version 3.0.0. The most commonly used extensions are:

  • tables
  • no_intr_emphasis
  • autolink

Kramdown

In addition to the defaults mentioned above,you can also turn on recognition of Github Flavored Markdown by passing an input option with a value of “GFM”.

e.g. in your _config.yml:

    kramdown:
	  input: GFM

Gustom Markdown Processors

Creat a new class in the Jekyll::Converters::Markdown namespace:

    class Jekyll::Converters::Markdown::MycustomProcessor
	  def initialize(config)
	    require 'funky_markdown'
	  rescue LoadError
	    STDERR.puts 'You are missing a library required for Markdown, Please Run:'
		STDERR.puts ' $[sudo] gem install funky_markdown'
		raise FatalException.new("Missing dependency: funky_markdown")
	  end

	  def convert(content)
	    ::FunkyMarkdown.new(content).convert
	  ned
	end

Once you’ve created your class and have it properly setup either as a plugin in the _plugins floder or as a gem, specify it in your _config.yml

    markdown::MyCustomProcessor

Front Matter

e.g.

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

you can set predefined variables or even creat custom ones of your own.

Predefined Global Variables

Predefined global variables that you can set in the front matter of a page or post.

  • layout
    • set the sepcified layout file to use.
      • Use the layout file name without the file extension.
    • Layout files must be placed in the _layouts directory.
  • permalink
    • default:/year/month/day/title.html
    • you can set this variable and it will be used as thi final URL.
  • published
    • Set to false if you don’t want a specific post to show up when the site is generated
  • category categories
    • you can specify one or more categories that the post belongs to.
    • Categories can be specified as a YAML file or a space-separated string.
  • tags
    • Similar to categories.
    • Also like categories, tags can be specified as a YAML list or a space-separated string.

Custom Variables

e.g. you can use in your layout to set the page title:

    <!DOCTYPE HTML>
	
	  
	    Jekyll learning note
	  

	  
	  ...
</pre>

### Predefined Variables for Posts ###

These are available out-of-the-box to be used in the front matter for a post

* data
	* A date here overrides the date from the name of the post. This can be used to ensure correct sorting of posts.

## **Writing posts** ##

## The Posts Folder ##

the **_posts** folder

### Creating Post Files ###

### Content Formats ###



    ---
	Front Matter
	---




### Including images and resources ###
One common solution:

create a folder in the root of the project directory called **assets** or **downloads**,
e.g.



    ...which is shown in the screenshot bolow:
	![My helpful screenshot](http://openefit.github.io/assets/screenshot.jpg)

	...you can [get the PDF](http://openefit.github.io/assets/mydoc.pdf) directly




You can skip the http://openefit.github.io variable if you know your site will only ever be displayed at the root URL of your domain. In this case you can reference assets directly with just /path/file.jpg

### Displaying an index of posts ###

e.g. creat a list of links to your blog post:


    
    
	  \{\% for post in site.posts \%\}
	  \  
  • 
	  \	   
	  \  
    • 
	  \{\% endfor \%\}
	




the **post** variable only exists inside the **for** loop above. If you wish to access the currently-rendering page/posts's variables(the variables of post/page that has the **for** loop in it), use the **page** variable instead.

### Post excerpts ###

Each post automatically takes the first block of text from the beginning of the content to the first occurrence of **excerpt_separator**,and sets its as the **post.excerpt**.


    
    
	  \{\% for post in site.posts \%\}
	  \  
  • 
	  \    
	  \ 	
	  \  
    • 
	  \{\% endfor \%\}
	




If you don't want wrap the excerpt in **p** tags:



    




If you don't like the automatically-generated post excerpt, it can be overridden by adding **excerpt** to your post's YAML Front Matter. Completely disable it by setting your **excerpt_separator** to "".

as with any output generated by Liquid tags, you can pass the **| strip_html** flag to remove any html tags in the output. This is particularly helpful if you wish to output a post excerpt as a **meta="description"** tag within the post **head**,or anywhere else having html tags along with the content is not desirable.

### Highlighting code snippets ###

Jekyll also has built-in support for syntax highlighting of code snippets using either Pygments or Rouge, and including a code snippet in any post is easy.Just use the dedicated Liquid tag as follows:


    \{\% highlight ruby \%\}
	\def show
	\	@widget = Widget(params[:id])
	\	respond_to do |format|
	\		format.html # show.html.erb
	\		format.json { render json: @widget}
	\	end
	\end
	\{\% endhighlight \%\}



## **Working with drafts** ##
Drafts are posts without a date.
creat a **_drafts** folder in your site's root and creat your first draft:



    |-- _drafts/
	|   |-- a-draft-post.md




To preview, **jekyll serve** or **jekyll build** with the **--drafts**.

## **Creating pages** ##

## Homepage ##
**index.html** in the site's root

even the homepage can use layouts and/or includes.

## Where addition pages live ##
There are two main ways of creating pages:

* Place named HTML files for each page in your site's root folder

* Create a folder in the site's root for each page, and place an index.html file in each page folder.

(The only difference being the resulting URLs).

## Named HTML files ##


    .
	|-- _config.yml
	|-- _includes/
	|-- _layouts/
	|-- _posts/
	|-- _site/
	|-- about.html    # => http://example.com/about.html
	|-- index.html    # => http://example.com/
	| contact.html  # => http://example.com/contact.html




## Named folders containing index HTML files ##


    .
	| _config.yml
	| _includes/
	| _layouts/
	| _posts/
	| _site/
	| about/
	|   | index.html  # => http://example.com/about/
	| contact/
	|   | index.html  # => http://example.com/contact/
	| index.html      # => http://example.com/




## **Variables** ##

## Global Variables ##

* site
	* Sitewide information + configuration setting from **_config.yml**.

* page
	* Page specific information+the YAML front matter. Custom variables set via the YAML Front Matter will be available here.

* content
	* In layout files, the rendered content of the Post or Page being wrapped. Not defined in Post or Page files.

* paginator
	* Wthen the **paginate** configuration option is set,this variable becomes available uso.

## Site Variables ##
* site.time
	* The curret time (when you run the **jekyll** command).

* site.pages
	* A list of all Pages.

* site.posts
	* A reverse chronalogical list of all Posts.

* site.related_posts
	* contains a list of up to ten related Posts.
	* these are low quality but fast to compute. For high quality but slow to compute results, run the **jekyll** command with the **--lsi**(latent semantic indexing) option.

* site.static_files
	* A list of all static files(i.e. files not processed by Jekyll's converters or the Liquid renderer). Each file has three properties: **path**, **modified_time** and **extname**.

* site.html_pages
	* A list of all HTML Pages.

* site.collections
	* A list of all the collections.

* site.data
	* A list containing the data loaded from the YAML files located in the _data directory.

* site.documents
	* A list of all documents in every collection.

* site.categories.CATEGORY
	* The list of all Posts in category

* site.tags TAG
	* The list of all Posts with tag **TAG**.

* site.[CONFIGURATION_DATA]
	* All the variables set via the command line and your **_config.yml** are available through the **site** variable. 
	* For example, if you have ` **url: http::mysite.com** ` in your configuration file.then in your Posts and Pages it will be stored in site.url.Jekyll does not parse changes to **_config.yml** in **watch** mode, you must restart Jekyll to see changes to variables.

## Page Variables ##
* page.content
	* The content of the Page, rendered or  unrendered depending upon what Liquid is being processed and what the **page** is.

* page.title
	* The title of the Page.

* page.excerpt
    * The un-rendered excerpt of the Page.

* page.url
	* The URL of the Post without the domain, but with a leading slash,e.g.**/2008/12/14/my-post.html**

* page.date
	* The Date assigned to the Post.
	* This can be overridden in a Post's front matter by specifying a new date/time in the format **YYYY-MM-DD HH::MM::SS**(assuming UTC),or **YYYY-MM-DD HH:MM:SS +/-TTTT** (to specify a time zone using an offset from UTC.e.g. **2008-12-14 10:30:00 +0900**).

* page.id
	* An identifier unique to the Post(useful in RSS feeds).e.g.**/2008/12/14/my-post**

* page.categories
	* The list of categories to which this post belongs.
	* Categories are derived from the directory structure above the **_post** directory. For example, a post at **/work/code/_posts/2008-12-24-closures.md** would have this field set to **['work', 'code']**.
	* These can also be specified in the YAML Front Matter.

* page.tags
	* The list of tags to which this post belongs.
	* These can bo specified in the YAML Front Matter.

* page.path
	* The path to the raw post or page. Example usage: Linking back to the page or post's source on Github. 
	* This can be overridden in the YAML Front matter.

* page.next
	* The next post relative to the position of the current post in site.posts.
	* Returns nil for the last entry.

* page.previous
	* The previous post relative to the position of the current post in **site.posts**.
	* Returns nil for the first entry.

* page.[MY_OWN_SPECIFY]

## Paginator ##
* paginator.per_page
* paginator.posts
* paginator.total_posts
* paginator.total_pages
* paginator.page
* paginator.previous_page
* paginator.previous\_page_path
* paginator.next_page
* paginator.next\_page_path