Notes

Jekyll and Jekyll-Bootstrap Notes

Online Resources

General help

Sample pages

R Markdown and Jekyll

Lanyon theme (currently used by this site)

Markdown and Kramdown Syntax

Installation

The install of Jekyll is straightforward with the RubyGems package manager.

gem install jekyll

If you want to keep your local Jekyll installation in sync with the version running on Github Pages, then install the Github Pages gem instead of the Jekyll gem as follows.

gem install github-pages

Quickstart with Jekyll

Generate new Jekyll site directory from scratch

$ jekyll new <directory>

Clone template, here Lanyon

Make sure you create an empty tgirke.github.io repos on GitHub first.

$ git clone https://github.com/poole/lanyon.git tgirke.github.io
$ cd tgirke.github.io
$ git remote set-url origin git@github.com:tgirke/tgirke.github.io.git
$ git push origin master

Now you should see your web repos here: https://github.com/tgirke/tgirke.github.io. Your web site’s URL is this: http://tgirke.github.io.

Add GitHub page to an existing project repo

By adding a gh-pages branch to an existing GitHub project repo one can generate a web site for any project. Here is how.

Basic structure of Jekyll site

When the below directory structure is built using Jekyll, the output is a static web site generated under the _site folder. Since GitHub uses Jekyll the static web site is automatically generated by GitHub. All source pages should be kept in the project’s root directory or under _posts. Never edit any pages under _site.

project root
|
|-- _config.yml
|-- index.html
|
|-- _includes
|       |-- head.html
|       |-- ...
|
|-- _layouts
|       |-- page.html
|       |-- post.html
|       |-- ...
|
|-- _posts
|       |-- 2015-01-01-blog.md
|       |-- ...
|
|-- _site
|       |-- ...

To render a Jekyll site locally, cd into its directory (e.g. tgirke.github.io) and then run the following command.

$ jekyll serve -w

Then direct your browser to: localhost:4000

Commit changes to github

$ git add -A :/; git commit -am "some edits"; git push -u origin master

Draft pages

To maintain drafts of pages that should be hidden on the life page, you can do this in a _drafts folder at the root level. Jekyll ignores the posts in the drafts folder when building the site, but at the same time provides a convenient command-line argument to include them in the build on your local system.

$ jekyll serve --drafts

Code chunks and syntax highlighting

To create code boxes with syntax highlighting support for your programming language, use the following code tags (here for ruby):
{% highlight ruby linenos %}...{% endhighlight %}
Dropping the linenos option will eliminate the line numbering. Here is an example for some R code:

############################
## appendCounter Function ##
############################
## Author: Thomas Girke
## Last update: 03-Oct-15

## Function to append occurrence counter to entries in character 
## vector and return the results as named vector where the 
## original data are in the same order in the data slot
## and the counting result in the name slot.
appendCounter <- function(x, sep="_") {
    names(x) <- sprintf(paste0("%0", as.character(nchar(
                        length(x))+1), "d"), seq_along(x))
    tmp <- sort(x)
    f <- table(tmp)
    tmp2 <- unlist(sapply(names(f), function(z) paste(z, 1:f[z], 
                   sep=sep)))
    names(tmp2) <- names(tmp)
    names(x) <- tmp2[sort(names(tmp2))]
    return(x)
}
## Usage:
x <-  c("a", "b", "c", "b", "h", "c")                                            
appendCounter(x, sep="_")

Code hosted on GitHub Gist can be directly included in a page simply by providing the corresponding identifier of the Gist entry in the Markdown source following this syntax: {% gist c26daac0f647f1732a58 %}

More detailed information on code highlighting can be found here:

Improve code highligthing in Jekyll pages

Girke Lab Research and Teaching Site