jekyll-refergen

Don’t forget to include a reference at the end of your posts.

1. Gem Installation

   • Add to your Gemfile:

     gem 'jekyll-refergen', git: 'https://github.com/yourname/jekyll-refergen.git'

   • Or after publishing to rubygems.org:

     gem 'jekyll-refergen'

   • Run bundle install

2. _config.yml Configuration

   refergen-plugin:
     collections: ["posts", "wiki"] # Specify which collections to process

   • The plugin processes all documents in the listed collections.

3. Usage Examples

   • Deduplicate by URL (same URL → same reference number):

     [Example1](https://www.example.com), [Example2](https://www.example2.com), [Again Example1](https://www.example.com)

     Renders as:

     Example1<sup><a href="#ref-1" id="ref-link-1">[1]</a></sup>, Example2<sup><a href="#ref-2" id="ref-link-2">[2]</a></sup>, Again Example1<sup><a href="#ref-1" id="ref-link-3">[1]</a></sup>
     
     ---
     ## Reference
     1. <a id="ref-1"></a>[Example1](https://www.example.com) ^ <a href="#ref-link-1">a</a> <a href="#ref-link-3">b</a><br/>
     2. <a id="ref-2"></a>[Example2](https://www.example2.com)<br/>

     When the same URL is referenced multiple times, the Reference section shows ^a b c format where each letter links to the corresponding reference location in the text.

   • Custom reference label: use the Markdown link title ("..." or unquoted) as the reference display name.

     [Visible text](https://www.example.com "Custom label")
     [Another link](https://www.example.com Custom label)

     Renders as:

     Visible text<sup><a href="#ref-1" id="ref-link-1">[1]</a></sup>
     Another link<sup><a href="#ref-1" id="ref-link-2">[1]</a></sup>
     
     ---
     ## Reference
     1. <a id="ref-1"></a>[Custom label](https://www.example.com) ^ <a href="#ref-link-1">a</a> <a href="#ref-link-2">b</a><br/>

4. Local Test (example)

   • Install dependencies:

     bundle install

   • Prepare a test Jekyll site (create one if needed):

     bundle exec jekyll new demo-site --skip-bundle
     cd demo-site
     bundle add ../jekyll-refergen # reference local plugin

   • Add plugin to _config.yml:

     plugins:
       - jekyll-refergen
     refergen-plugin:
       collections: ["posts"]

   • Add the usage examples to a post, then build/serve:

     bundle exec jekyll build
     bundle exec jekyll serve

   • In the rendered HTML, verify same URLs share the same number and the title is used as the reference label when provided.

1. Create .github/workflows/deploy.yml
2. Add the following workflow:

name: Build & Deploy Jekyll

on:
  push:
    branches: [ master ]

jobs:
  build-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1'
      - name: Install dependencies
        run: bundle install
      - name: Build site
        run: bundle exec jekyll build
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site

• This workflow builds your Jekyll site and deploys the _site folder to GitHub Pages on every push to the master branch.
• If your Gemfile includes jekyll-refergen, the plugin will work in the GitHub Actions environment.

• The plugin works with Jekyll 3.x and 4.x.
• Custom gem plugins are not supported on the official GitHub Pages build server. You must use GitHub Actions or another external build server for deployment.