Jekyll: How to use custom plugins with GitHub pages?

Question

It turns out that custom ruby plugins don't work on GitHub pages because of security concerns.

I'm trying to add a plugin (this one) to the _plugins folder of my Jekyll project, but when I deploy it to GitHub it is ignored.

Question: Is there a way to workaround this? Has anyone found a solution?

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

Answer 1

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.

Answer 2

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/

Answer 3

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

Answer 4

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.