跳转至

Jekyll

  1. What is a page? Where do I put pages?

Pages can be HTML or Markdown files. Some other files might work as well, e.g. plain text, JavaScript or even Python, but Jekyll has built-in Markdown support that converts it into HTML during the build.

Place them in the root folder and organise them in sub-folders. Jekyll will reflect the structure.

  1. What is front matter?

Metadata you accessible via page, place at the head of a file. The format is YAML between two lines of ---. For example, {{ page.my_number }} is 5 given:

---
my_number: 5
---

You must have at least a blank front matter with only two lines of --- for the page to be processed (e.g. convert Markdown to HTML, fills Liquid, converts SASS to CSS). If you leave it, files will be copied to _site as it. You can use https://github.com/benbalter/jekyll-optional-front-matter (used by GitHub Pages as well) to avoid this.

  1. Can I avoid adding front matters?

https://github.com/benbalter/jekyll-optional-front-matter.

  1. How to specify default front matters?

Reference: https://jekyllrb.com/docs/configuration/front-matter-defaults/.

In _config.yml, add defaults. It specifies the scope and values.

  1. How does layout work?

Together with include, it is similar to Django template.

Layouts are in _layouts folder. For example, _layouts/default.html is:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
  </head>
  <body>
    {{ content }}
  </body>
</html>

content is the rendered content of the page that uses this layout. To use it, write layout: default in the front matter:

---
layout: default
title: Home
---
<h1>Hello World!</h1>

You can use layout: <another_layout> to base a layout on another one.

  1. How does include work?

A piece of markup you can include in other pages. Placed in _includes folder. For example, _includes/navigation.html is:

<nav>
<a href="/">Home</a>
</nav>

To include it in _layouts/default.html, use {% include navigation.html %}:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <title>{{ page.title }}</title>
  </head>
  <body>
    {% include navigation.html %}
    {{ content }}
  </body>
</html>

You can also include a file relative to the current file via {% include_relative <relative_path> %}, but parent directories are not supported (i.e. no ../some-page.md).

  1. What is data?

Apart from page metadata in front matters, you can have dedicated data in _data folder in YAML, JSON or CSV formats. For example, _data/navigation.yml:

- name: Home
  link: /
- name: About
  link: /about.html

The data is then available at site.data.navigation.

  1. How about assets?

JavaScript and CSS files work as normal. Just reference them in HTML directly. If you add a front matter however, you can use Liquid in it.

  1. What are posts?

In Jekyll, posts are specially treated pages. Placed in _posts with a date in the file name (e.g. _posts/2018-08-20-bananas.md), page.title will be Bananas and page.date will be 2018-08-20. All posts are available at site.posts.

  1. What language is Jekyll written in?

Ruby.

  1. How to create a new Jekyll site?

jekyll new mysite

  1. What is the point of running jekyll commands with bundle exec prefixed?

Gems are Ruby packages. Bundler installs and manages gems. This is similar to Node's NPM where NPM is a Node package that installs Node packages.

By using bundle exec, jekyll respects Gemfile which acts just like package.json.

(A side note: There is also a RubyGem which is a Ruby package manager. Bundler is also installed via RubyGem. It cannot handle dependency conflicts properly however and Bundler is the de-facto tool to manage packages.)

  1. How to build a site?

bundle exec jekyll build. The default output folder is _site.

  1. How to start the development server?

bundle exec jekyll serve --livereload. It does jekyll build and serves it at http://localhost:4000 by default. It rebuilds automatically on changes and --livereload will force the browser to reload as well.

  1. What is Jekyll's templating language Liquid?

It has three main concepts:

  1. Object: Output variables (e.g. {{ page.title }}). There are many predefined variables provided by Jekyll to Liquid, check https://jekyllrb.com/docs/variables/. Similar to Django variables.
  2. Tag: Define the logic and control flow for templates. For example, {% if <condition> %} and {% endif %}. Similar to Django tags.

  3. Filter: {{ <variable> | <filter>}}. For example, {{ "hi" | capitalize }} gives you Hi. Similar to Django filters.

  4. How to put pages in a different folder rather than the root directory?

In _config.yml, source: <source_dir>. For example, source: docs.

This helps to avoid polluting the actual content (source) folder.

  1. What gems/plugins are supported in GitHub Pages?

Refer to https://pages.github.com/versions/. If not supported, build locally before the commit and push.