README.md

Jekyll GH-Pages Tagging
GitHub Action

Issues 🔸 Releases

Elapsed Project Time

If you like this repository, please give it a ⭐ (it really does help)

⭐ Project Overview

An article tagging solution for Jekyll that is 100% compatible with GH-Pages

If you're using GitHub Pages in SAFE mode, then you already know that most plugins are disabled and only a small number of plugins are whitelisted. One of the plugins you can't use is jekyll-tagging - which makes managing tags for your blog articles difficult.

This project provides a fully-automated solution for Jekyll tag management that is 100% compatible with GitHub Pages by doing the work through GitHub Actions instead of a Jekyll plugin. Like most of my projects, this one was inspired by my own need for the solution.

If you've got an idea you'd like to see implemented, submit a feature request and it will be considered for inclusion in an upcoming release.

❓ What Does It Do?

1. Scans the posts_dir for a list of blog articles
2. Extracts a list of tags used in those articles
3. Creates config files in tags_dir for new tags
   • Optionally creates config files in feeds_dir for new tags also
4. Deletes config files for tags & feeds which are no longer in use
5. Commits changes to git and pushes to repo

Tag Files - form a Jekyll Collection which can be used to index blog articles according to their associated tag(s).

Feed Files - allow you distribute your articles in ATOM (RSS) format and curate your feeds according to their associated tag(s).

📂 Usage

Inputs

posts_dir:
    description: "Path to '_posts' directory from root"
    required: true
    default: "_posts"
tags_dir:
    description: "Path to '_tags' directory from root"
    required: true
    default: "_tags"
tags_layout:
    description: "Layout used by tag files"
    required: true
    default: "tags"
feeds_dir:
    description: "Path to '_feeds' directory from root"
    required: false
    default: "_feeds"
feeds_layout:
    description: "Layout used by feed files"
    required: false
    default: "feed"
prune_tags:
    description: "Remove unused tags"
    required: false
    default: "true"

Example Workflows

name: Jekyll GH-Pages Tagging Workflow

on:
    # Trigger when Markdown files pushed to docs/_posts on the master branch 
    push:
        branches:
            - master
        paths:
            - 'docs/_posts/*.md'
    # Allows this workflow to be triggered manually
    workflow_dispatch:

jobs:
    generate_tags:
        runs-on: ubuntu-latest
        permissions:
            contents: write
        steps:
            - name: Checkout
              uses: actions/checkout@v4
            - name: Generate Tags
              uses: ragdata/jekyll-ghpages-tagging@master
              with:
                posts_dir: "docs/_posts"
                tags_dir: "docs/_tags"
                tags_layout: "tags"
                feeds_dir: "docs/_feeds"
                feeds_layout: "feed"
              env:
                GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

You can find a copies of a standalone workflow, reusable workflow and caller using this GitHub Action in my Workflow Templates repository.

^ Top

❤️ Project Supporters

Click here to find out about available sponsorship opportunities!

If sponsorship isn't right for you, but you have found my work to be useful in some way,
would you please consider buying me a coffee to help keep me going?

^ Top

🚧 Author / Maintainer

^ Top

🔐 Security

While I always good security practices, 100% security can never be guaranteed in any software package. The Jekyll GH-Pages Tagging Action is provided AS IS, and without warranty. You can find more details in the LICENSE file included with this repository.

If you discover any issue regarding the security of this project, please disclose that information responsibly by sending a security advisory. PLEASE DO NOT CREATE AN ISSUE OR DISCUSSION TOPIC. You can read more about this project's security policies HERE

^ Top

©️ Copyright & Attributions

This project incorporates ideas and / or code crafted by the following talented individuals:

• Article: How do I tag posts in Jekyll? Jekyll tagging made simple
  Copyright © 2020 - Joseph Zammit @ Untangled Development

"We see much further, and reach much higher,
only because we stand upon the shoulders of giants"

^ Top

📖 Resources

• Jekyll Website
• GitHub Pages Dependencies (list of plugins supported by gh-pages)
• Ragdata's Favourite Jekyll Resources

^ Top

⚖️ License

Copyright © 2024 Darren (Ragdata) Poulton

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

^ Top

If you like this repository, please give it a ⭐ (it really does help)

Copyright © 2024 Redeyed Technologies