Chris Weaver - Jekyll

Home / Notes / Jekyll

Jekyll

web dev

This website is built with Jekyll.

Jekyll is a static webpage generation framework that uses liquid for templating. Can work with Markdown or HTML. Very good, simple documentation, can also be hosted by github for free with github pages.

Dev Environment

Ruby & gems

See: https://jekyllrb.com/docs/installation/

Or setup as a devcontainer in vscode with docker

Install Remote - Containers
ctrl + p to open the command pallete
Select:
- Remote-Containers: Add Development Container Configuration Files...
- Find Ruby & select your version and additional options
  - At the time of writing use Ruby 2.7
Then ctrl + p again & select Remote-Containers: Rebuild & Reopen as container

New project

gem install jekyll bundler
jekyll new [project-name]
cd [project-name]

Run

bundle exec jekyll serve

Variables

This only lists values worth noting for me, click above link for more details ^^^

Site

Variable	Description	Use
site.pages	Array of all pages	`{%- for p in site.pages %}{% endfor -%}`
site.posts	Array of all posts	`{%- for p in site.pages %}{% endfor -%}`
site.collections	Array of Collections in the site
site.data	data in _data directory
site.tags.TAG	Array of all posts with specific tag
site.categories.CATEGORY	Array of all posts with specific
site.url	url of site

Snippets

Loop & filter posts

// Loop through site.posts
{% assign items = site.posts %}
{%- for post in items %}

  // Use page.filter to filter out unwanted posts on current page
  // Implement 'filter' in the front matter of the page implementing component
  {% if post.categories contains page.filter %}

  // Display post details
  {{post.title}} {{post.description}} {{post.date | date: "%d-%m-%Y"}} {{post.url}}
  ...

  {% endif %}
{% endfor -%}

Note: site.categories.{category_name} would also work here instead of the if statement

Breadcrumbs

<div id="breadcrumbs" class="mb-3">
  <small>
    {% assign crumbs = page.url | remove:'/index.html' | split: '/' %}
    <a href="/">Home</a>
    {% for crumb in crumbs offset: 1 %}

    {% if forloop.last %}
        / {{ page.title }}
    {% else %}
    / <a href="{% assign crumb_limit = forloop.index | plus: 1 %}{% for crumb in crumbs limit: crumb_limit %}{{ crumb | append: '/' }}{% endfor %}">{{ crumb | replace:'-',' ' |    remove:'.html' | capitalize }}</a>
    {% endif %}
    {% endfor %}
  </small>
</div>

Syntax highlighting

Add the following to _config.yml. More options can be found Jekyll Markdown Configuration

kramdown:
    syntax_highlighter_opts:
        line_numbers: false
        tab_width: 2
        css: class

find a Rouge compatible stylesheet, some can be found at Pygments CSS Themes. I use Monokai with some minor changes.

Include markdown in html

{% capture markdown_include %}{% include post.md %}{% endcapture %}
{{ markdown_include | markdownify }}

Pass-through variables to includes

From the template:

{% include sub_heading.html title="Title Here" date="July 2014" footnote="This is a footnote" %}

In the include:

<div class="flex-container mb-2">
    <div class="row">
        <div class="col-8">
            <h6 class="d-inline"><b>{{ include.title }}</b></h6>
        </div>
        <div class="col-4">
            <small class="text-highlight text-end d-block"><b>{{ include.date }}</b></small>
        </div>
    </div>
    {% if include.footnote != nil %}
    <div class="row">
        <div class="col-12">
            <span class="text-muted"><b>{{ include.footnote }}</b></span>
        </div>
    </div>
    {% endif %}
</div>

chris ~ $ ▂