This is a guide to maintaining the Kwiat group website using Jekyll and other tools.

This guide was written by Rebecca Holmes. Contact me at rholmes4@illinois.edu if you need help.

NOTE: I built this website using Jekyll on Windows 7. Jekyll and most of the other tools needed to maintain the website are also available for Mac and Linux, but I don't have any experience using them on other platforms.

• Introduction
  • But first, wait! Don't edit those HTML files on the server!
  • What is Jekyll?
• Installation and setup
  • Clone this GitHub repository
  • Install Ruby and Jekyll
  • Install bibtex2html
  • Optional: Install Mendeley
• Running Jekyll
  • Updating the live website
  • Hosting the site locally
• A brief description of how Jekyll works
  • YAML frontmatter
  • Markdown
  • Liquid
• How to do specific tasks
  • Adding a news post
  • Changing information about group members
  • Adding a new page and editing the navbar
  • Managing research topics
    • Editing the content of an existing topic
    • Changing the order of existing topics
    • Removing a topic
    • Adding a new topic
  • Managing Publications
    • Troubleshooting publications
    • Bypassing publications management

The Kwiat group website is maintained using Jekyll and files hosted on GitHub. This guide contains an overview of how Jekyll generates the site, and instructions for specific tasks like adding news posts or editing the navbar. It does not explain every detail of how Jekyll works, or every possible feature you might want to use. For more about what Jekyll can do, read the Jekyll documentation here: http://jekyllrb.com/docs/home/

Seriously, don't do it. All will be explained! In short, if you edit the HTML files (or any files) that are already on the server, your changes will not be visible to Jekyll or committed to the GitHub repository, and they will be lost the next time someone runs Jekyll and updates the website. Instead, what you should do is:

1. Edit a file in this GitHub repository
2. Run Jekyll
3. Copy the files generated by Jekyll to the server that hosts the website

Whatever you're trying to change (on Paul's orders, I assume), there's probably an easier way to do it using Jekyll. I know--everyone who writes a guide to some complicated-sounding program insists that everything will be so easy once you learn to use it. But I'm going to tell you that too. For example, once you set up Jekyll you can edit most of the text on the website without ever looking at an HTML file. So resist the urge to edit that file, and read on.

Jekyll is a tool that takes pieces of content (like text files) and instructions for displaying them (like HTML layouts) and builds a website. It takes care of tedious things you might otherwise have to do manually, like updating the navbar on each page if you want to add a new link. Another common way to accomplish this is by building a dynamic site using PHP or other server-side languages. The advantages of using Jekyll are primarily that you don't need to learn a server-side language, and the site can be hosted anywhere without worrying about whether the host server supports your dynamic content.

The whole process of building the website happens on your computer, and the result is a static website that can be uploaded to a server. So while using Jekyll might seem intimidating, it's a great way to build a complex website without knowing much more than basic HTML and CSS. Many tasks won't even require more than editing plain text. You can do it!!

You must complete a few steps before you can maintain the website with Jekyll from your own computer.

The GitHub repository group-website-jekyll stores a "master" version of the files needed to generate the website. You can download ("clone") these files to your own computer and use them. If you make changes, you can tell GitHub to sync them to the master version so there will be a single version of the files that multiple people can access.

1. If you don't already have one, you will need to make a GitHub account. You will also need to contact one of the administrators of the lab GitHub group (KwiatQIM) and have your account added to the group.

2. Install and set up GitHub Desktop for Windows.

3. From GitHub Desktop, select the KwiatQIM group, find the repository group-website-jekyll, and click "Clone." This will copy the files from the repository to a folder on your computer.

The GitHub help page can tell you more about using GitHub, but the basic idea is as follows:

• If someone else has made changes to the files in the group-website-jekyll repository, you can (and should) sync them to your local version by clicking "Sync" in the upper right-hand corner of GitHub Desktop. This will keep the copies of the website files on your computer up to date if several people are making changes.
• If you make a change to a file in the respository (edit some text, delete an unneeded file, etc.) you can (and should) save that change to the master version by "committing" the change from GitHub Desktop, which will automatically prompt you whenever it notices that files have changed. Finally, you should click "Sync" to upload your changes to the master version and finalize the change.

Jekyll is based on the programming language Ruby, which you must install in order to run Jekyll. (You don't need to know how to use Ruby.) Once Ruby is installed, you can easily install Jekyll and a few other necessary programs.

1. Install Ruby using RubyInstaller. Install the latest DevKit, available on the RubyInstaller downloads page.

2. After extracting the DevKit package, use the command prompt (type cmd in the Windows search bar) to cd to the directory where you extracted it. Run the following commands:

   ruby dk.rb init
ruby dk.rb install


3. Install the RubyGem Jekyll by typing:

   gem install jekyll


4. Install the RubyGem kramdown (a processor for Markdown, which we will use for simple text formatting):

   gem install kramdown


bibtex2html is a program that converts BibTeX files to HTML so a list of references can be displayed on a webpage. Jekyll uses it to process the BibTeX file publications_web.bib in the _bibliography directory. If it is not installed or installed in the wrong location, Jekyll will give an error when you try to run it, and the list of publications will not be generated.

If for some reason you are unable to successfully run Jekyll with bibtex2html, it is possible to disable this feature and preserve the current list of publications; however, managing future publications will be pain. See Managing publications.

1. Install bibtex2html from the bibtex2html home page. Use the Windows 1.95 installer. Put it in C:/Bibtex2html/bibtex2html.exe or Jekyll won't be able to use it. (This can be changed by editing bibjekyll.rb in the _plugins directory under the comment "call bibtex2html", but you will probably make someone else unhappy by changing it.)

Mendeley is an academic reference manager. It is used to organize the citations that appear on the Publications page of the website. If you follow a few steps, you can use Mendeley, plus a simple Python script and Jekyll's interface with bibtex2html to maintain the list of citations, including automatically linking to the DOI and to a hosted .pdf file if one is available. Details are in Managing publications.

If you don't need to add, remove, or edit the content of citations, you don't need to install Mendeley or make any changes to publications_web.bib. You can change certain formatting options (such as how the author names are abbreviated) in the style.bst file that bibtex2html uses.

If you've just copied the website files from GitHub to a new computer and you and haven't run Jekyll yet, the _site directory in your repository should be empty. When you run Jekyll, _site is where all the assembled pieces of the website will go--the finished product. GitHub will not sync the files in _site. You can always generate them again by running Jekyll.

To run Jekyll and fill the empty _site directory with the assembled website, use the command prompt to cd to group-website-jekyll. Then just enter the command

That's it! The _site directory should now be populated with the website files. The live website at http://research.physics.illinois.edu/QI/Photonics/ has not been updated, though.

After running Jekyll, just replace the contents of Photonics with the entire contents of _site. You can do this in Windows Explorer if you have access to the networked folder where our webspace is, or you can use SSH. Contact help@physics.illinois.edu if you need help acccessing the webspace.

If you're testing out changes, it can be useful to tell Jekyll host the website on your own computer so you can view it in a browser exactly as it will appear when it goes live. I recommend previewing all changes this way.

It can also be nice to set Jekyll to automatically rebuild the site when you make changes. To do both of these things, use the server command with --watch:

This tells Jekyll to build the website, to host the contents of _site locally, and to automatically rebuild if you change anything. Now you should see the website if you point your browser to http://localhost:4000/QI/Photonics/. (Reminder: what you see are still just files on your computer--you need to copy them to our webspace to make any changes live.)

If you just want to know how to update a specific part of the website (like adding a news post), scroll down past this section to How to do specific tasks. If you want an overview of what Jekyll is doing when you run it, read on.

Take a look at the list of files and folders in the group-website-jekyll repository. When you run Jekyll, it looks through all those files and folders, and follows certain rules to assemble the pieces they contain into a finished website in the _site directory. These are the main types of files and folders Jekyll looks at (for more details, see http://jekyllrb.com/docs/structure/):

1. Folders with no _ (underscore) before their names. Jekyll just copies these directly to _site without changing anything. Example: img, which contains all the images used on the website. css contains the CSS stylesheets for the website, which can be edited just like regular CSS. Files with no _ and no YAML frontmatter (I'll explain what this is soon) will also be copied to _site verbatim.

2. HTML files with no _ before their names that also contain YAML frontmatter. Example: people.html, the page with information about the people in our group. Jekyll processes each of these to create an HTML file in _site. With current settings, people.html ends up in _site/people/index.html. (index.html, the home page of the website, just goes to _site with no subfolder.)

3. Folders with _ before their names. These folders are not copied to _site directly, but contain content and information that Jekyll uses to assemble the website. Examples:

   • _layouts contains HTML files which define page layouts that can be reused for many pages. For example, _layouts/default.html is a layout which puts a navbar at the top of the page and a footer at the bottom, and also includes some CSS and Javascript that is used on most pages in the website.
   • _includes contains pieces of content which can be inserted into pages with a special command. For example, {% include navbar.html %} will insert the code for a navbar wherever Jekyll finds it. {% markdown aboutus.md %} will process and insert the Markdown text in aboutus.md, which appears under "About us" on the front page of the website. (More about Markdown later.)
   • _data contains YAML files with well-formatted data that Jekyll can use. For example, group_members.yml contains a list of current group members, their email addresses, and the filenames of headshot images. Jekyll uses it to generate the final People page.
   • _plugins contains Ruby scripts which give Jekyll extra features. For example, bibjekyll.rb handles the list of citations on the Publications page.

4. _config.yml is a special file which contains Jekyll's configuration information. You probably don't need to edit it unless you want to host the site locally (see Hosting the Site Locally, above).

YAML frontmatter is information contained between two lines of --- at the start of a file, like this example from people.html:

The YAML frontmatter gives Jekyll information and instructions when processing the file that contains it. The layout variable tells Jekyll which of the layouts in _layouts it should use for this page--in this example, the People page will use the default layout in _layouts/default.html. The title variable tells Jekyll the title of the page. These variables can be accessed elsewhere on the website. For example, default.html automatically sets the title of each page to page.title, and the navbar uses page.title to decide which page is the current page and highlight its link.

Jekyll will only process HTML documents in the main directory if they have YAML frontmatter. In other contexts, it is optional. Read more about YAML in the Jekyll documentation: http://jekyllrb.com/docs/frontmatter/.

Markdown is a text-to-HTML tool. It allows you to write good-looking content for the web without using HTML tags. Markdown files look more like regular text files, which makes them easier to read and work with. Markdown processes .md files to insert all the ugly HTML tags that make text display properly on the web.

Most of the text content for the group website is in Markdown files in the _includes directory.

• This is a useful Markdown cheat sheet: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

• And here's an online Markdown editor you can use in your browser: http://dillinger.io/

Markdown will also process many HTML tags, if you need to sneak some in there.

Jekyll uses the Liquid templating language to handle variables, some logic operations, and to enable "including" files in other files. All the tags you see with { } or {{ }} are Liquid tags.

• This is a good introduction to using Liquid: http://docs.shopify.com/themes/liquid-basics

A few examples of how Liquid is used for the Kwiat group website:

• In the default layout default.html, the variable page.title is used to make the