Jekyll: How to use custom plugins with GitHub pages?

If you want to make Jekyll site run as if it were local, such as let the custom plugins work properly, here is a way really convenient to build and deploy the Jekyll site to Github Pages.

A Github Action to deploy the Jekyll site conveniently for GitHub Pages. https://github.com/jeffreytse/jekyll-deploy-action

With this action, I think your issues can be settled perfectly.

Without a plugin

A reading time script does not require a plugin. I have created a collection of scripts that can be added without using a plugin. You can find them here. A reading time script is one of them.

Here you find the code:

{% capture words %}
{{ content | number_of_words | minus: 180 }}
{% endcapture %}
{% unless words contains '-' %}
{{ words | plus: 180 | divided_by: 180 | append: ' minutes to read' }}
{% endunless %}

Note that this code contains only Liquid and no Ruby. Therefore it can be used in your layout or in an include (without a plugin).

Optimizing the script

Suppose you have something like this:

<p>lorem ipsum</p>
<p>lorem ipsum</p>
<code>lorem ipsum</code>
<p>lorem ipsum</p>
<code>lorem ipsum</code>
<p>lorem ipsum</p>

Then you could remove the above code blocks like this:

{% assign preprocessed_content=post.content | replace: '<p>', '__p__' %}
{% assign preprocessed_content=preprocessed_content | replace: '</p>', '__/p__' %}
{% assign truncated_content=preprocessed_content | strip_html %}
{% assign cleaned_content=truncated_content | replace: '__p__', '<p>' %}
{% assign cleaned_content=cleaned_content | replace: '__/p__', '</p>' %}

Ofcourse this can be extended to support more tags.

Using the plugin anyway

If you REALLY want to use a plugin you can let your local machine or CloudCannon build your site and push the result to Github Pages. See also: https://learn.cloudcannon.com/jekyll/using-jekyll-plugins/

If you want to use your custom plugins, you have to "build" your site locally and then deploy it to the gh-pages branch yourself, as a collection of HTML, CSS and other files (not Markdown files anymore). You may want to try jgd command line to to help you do it all automatically. Just install it and then run:

$ jgd

The site will be packaged and then deployed to the gh-pages branch of your repo. More about it in this blog post of mine: Deploy Jekyll to GitHub Pages

If you don't what a local solution because it's time consuming, you could automate a process so that when you push changes to master it will automatically build your website locally and push the changes to the gh-pages branch.

You can achieve this by creating a pre-push hook in your repo (.git/hooks/pre-push) with the following content:

#!/bin/sh

# If any command fails in the bellow script, exit with error
set -e

# Set the name of the folder that will be created in the parent
# folder of your repo folder, and which will temporarily
# hold the generated content.
temp_folder="_gh-pages-temp"

# Make sure our main code runs only if we push the master branch
if [ "$(git rev-parse --symbolic-full-name --abbrev-ref HEAD)" == "master" ]; then
    # Store the last commit message from master branch
    last_message=$(git show -s --format=%s master)

    # Build our Jekyll site
    jekyll build

    # Move the generated site in our temp folder
    mv _site ../${temp_folder}

    # Checkout the gh-pages branch and clean it's contents
    git checkout gh-pages
    rm -rf *

    # Copy the site content from the temp folder and remove the temp folder
    cp -r ../${temp_folder}/* .
    rm -rf ../${temp_folder}

    # Commit and push our generated site to GitHub
    git add -A
    git commit -m "Built \`$last_message\`"
    git push

    # Go back to the master branch
    git checkout master
else
    echo "Not master branch. Skipping build"
fi

For more details please see my blog post.

You need an alternative to those plugins.

As detailed in "Building a Series List with Hugo Shortcodes":

Ruby plugin execution is disabled altogether on Github pages:

Plugins on GitHub Pages GitHub Pages is powered by Jekyll.
However, all Pages sites are generated using the -safe option to disable custom plugins for security reasons. Unfortunately, this means your plugins won’t work if you’re deploying to GitHub Pages.

You can still use GitHub Pages to publish your site, but you’ll need to convert the site locally and push the generated static files to your GitHub repository instead of the Jekyll source files.

I understand you mention:

Obviously I can generate html files locally and commit them to my repository. But that's not what I want.

Still, a static website generator (compatible with GitHub pages) like Hugo is to be considered in your case.

R.J Lorimer adds:

Hugo has the concept of Shortcodes, which are much like “Liquid Tags” in Jekyll.
Also like Jekyll, you can create custom shortcode tags.

However, the major difference is that in Hugo you can create them without resorting to actually writing Go code - see Create Your Own Shortcodes.
Because Hugo uses Go Templates for rendering the pages, shortcodes can use any and all Go template functions inside of them, as well as a whole list of custom Hugo functions added to help. This makes it arguably more powerful than a liquid-template solution, but still in a template file that can be easily updated on the fly.

Plus, Hugo does support MathJax, as seen in this article.

Update Nov. 2018: with Hugo 0.52, this tweet confirms (referencing this thread):

The inline shortcode is similar to the way Jekyll allows you to use Liquid tags within Markdown