jekyll-refergen

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

---

Gem Installation and Usage

1. Gem Installation

   • Add to your Gemfile: ruby gem 'jekyll-refergen', git: 'https://github.com/yourname/jekyll-refergen.git'
   • Or after publishing to rubygems.org: ruby 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): markdown [Example1](https://www.example.com), [Example2](https://www.example2.com), [Again Example1](https://www.example.com) Renders as: ```markdown Example1^[1], Example2^[2], Again Example1^[1]

   ---

   ## Reference

   1. Example1 ^ a b
      
   2. Example2
      `` 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/>
  

1. Local Test (example)
   • Install dependencies: bash bundle install
   • Prepare a test Jekyll site (create one if needed): bash bundle exec jekyll new demo-site --skip-bundle cd demo-site bundle add ../jekyll-refergen # reference local plugin
   • Add plugin to _config.yml: yaml plugins: - jekyll-refergen refergen-plugin: collections: ["posts"]
   • Add the usage examples to a post, then build/serve: bash 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.

---

Github Actions: Automatic Deployment

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.

---

Notes

• 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.