jekyll-scholar 7.2.3 → 7.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d71ae3f8a6557434f15bff3a23a2b9a0f434e600eef185a217958528283462ef
-  data.tar.gz: fe77a60644effaaf12155207bcf0681d4d6a43eb54a6df5f4b16336917fcb00c
+  metadata.gz: 8a25fc2a0dd6f5d888094afeff216e143e388bdb0b2c87c3df58b4b8da8898a9
+  data.tar.gz: 0d9a23dae92cbade063caed08ba5db363b345a8c13e4823284c881ad1b0b4f6f
 SHA512:
-  metadata.gz: 7d1ca51e476db2890e4d5bd22717bc4a03d1e74a9655fd389aa3ab01039903a0ef84ec7f96a6d4f7fd99c506691553ac8e4f2693e504e253eb65bb3babcdf69d
-  data.tar.gz: 588c268a9ae8a78249145fca5924ea433fa5f8c4618f4a6044653d57612d091abf03834124090a43a6756342c6f440c99addcf917f529e0f0c23dcfeb8759f16
+  metadata.gz: 5817e586d946392c4632e48c9d39f4bb8cb68ca0296641a1e370a8ee0eb305d795b8d506883df006c7dfcb3997fcbd31a3af6b3bb97690812c9f1d116ecb5d9b
+  data.tar.gz: 4bc025bd07d25bc68727f8e718b8356317bb97afe35d7968c3670928d60bcbd1e744c2b90cd2fff6b404b9be78650e36a613adf7abe7f526a750482ec239d59c

data/README.md

@@ -67,12 +67,13 @@ description of all options and their defaults, see
 | `source` | `./_bibliography` |  Indicates where your bibliographies are stored. |
 | `bibliography` | `references.bib` | Indicates the name of your default bibliography. For best results, please ensure that your bibliography is encoded as ASCII or UTF-8. A string that contains a `*` will be passed to `Dir::glob`, so `**/*.bib{,tex}` will find all files named `*.bib` and `*.bibtex` under `source`.  |
 | `allow_locale_overrides` | `false` | When `true`, allows the `language` entry in the BibTex to override the `locale` setting for individual entries. When the language is missing it will revert back to `locale`. The language value should be encoded using the two-letter [ISO 639-1](https://www.loc.gov/standards/iso639-2/php/code_list.php) standard. Ex. English = 'en', Spanish = 'es'. |
-| `sort_by` | `none` | Specifies if and how bibliography entries are sorted. Entries can be sorted on multiple fields, by using a list of keys, e.g. `year,month`. Ordering can be specified per sort level, e.g. `order: descending,ascending` will sort the years descending, but per year the months are ascending. If there are more sort keys than order directives, the last order entry is used for the remaining keys. |
+| `sort_by` | `none` | Specifies if and how bibliography entries are sorted. Entries can be sorted on multiple fields, by using a list of keys, e.g. `year,month`. Ordering can be specified per sort level, e.g. `order: descending,ascending` will sort the years descending, but per year the months are ascending. If there are more sort keys than order directives, the last order entry is used for the remaining keys. Special field `name` provides a fallback chain across named entities: `author` → `editor` → `institution` → `organization` → `publisher`, useful for bibliographies where all entries should be alphabetized together regardless of entity type. |
 | `order` | `ascending` | Specifies order bibliography entries are sorted in. Can be `ascending` or descending. Ordering can be specified per sort level, e.g. `descending,ascending` will sort in descending on the first key then ascending order on the second key. If there are more sort keys than order directives, the last order entry is used for the remaining keys. |
 | `group_by` | `none` | Specifies how bibliography items are grouped. Grouping can be multi-level, e.g. `type, year` groups entries per publication type, and within those groups per year. |
 | `group_order` | `ascending` |  Ordering for groups is specified in the same way as the sort order. Publication types -- specified with group key `type`, can be ordered by adding `type_order` to the configuration. For example, `type_order: [article,techreport]` lists journal articles before technical reports. Types not mentioned in `type_order` are considered smaller than types that are mentioned. Types can be merge in one group using the `type_aliases` setting. By default `phdthesis` and `mastersthesis` are grouped as `thesis`. By using, for example, `type_aliases: { inproceedings: article}`, journal and conference articles appear in a single group. The display names for entry types are specified with `type_names`. Names for common types are provided, but they can be extended or overridden. For example, the default name for `article` is *Journal Articles*, but it can be changed to *Papers* using `type_names: { article: Papers }`. |
 | `bibtex_filters` | `latex,smallcaps,superscript` | Configures which [BibTeX-Ruby](https://github.com/inukshuk/bibtex-ruby) formatting filters values of entries should be passed through. The default `latex` filter converts LaTeX character escapes into unicode, `smallcaps` converts the `\textsc` command into a HTML `<font style=\"font-variant: small-caps\">` tag, and `superscript` which converts the `\textsuperscript` command into a HTML `<sup>` tag. |
 | `raw_bibtex_filters` | ` ` | Configures which [BibTeX-Ruby](https://github.com/inukshuk/bibtex-ruby) formatting filters the raw BiBTeX entry (i.e. that available through `{{ entry.bibtex }}`) should be passed through. This can be used to e.g. strip excess newlines by using the `linebreaks` filter. |
+| `separate_links` | `false` | Experimental: If `true`, render each in-text citation in a citation group as a separate link (e.g. `[1, 2, 3]` would have 3 links, one to each citation). Otherwise, only render a single link to the first citation (default). May not work with citation styles that abbreviate ranges of citations, e.g. `[1-3]`. |
 
 
 ### Bibliographies
@@ -156,6 +157,20 @@ For more details about filters, see the corresponding section below or
 consult the [BibTeX-Ruby](https://github.com/inukshuk/bibtex-ruby)
 documentation.
 
+To create bibliographies where all entries are alphabetized together
+regardless of whether they have authors, editors, or institutional
+publishers, you can use the special `name` sort field in your configuration:
+
+```yaml
+scholar:
+  sort_by: name
+```
+
+This will sort entries by their primary named entity, using the fallback chain:
+`author` → `editor` → `institution` → `organization` → `publisher`. For example,
+a book by an author, an edited volume, and a technical report would all be
+sorted alphabetically together.
+
 If you need to limit the number of entries in your bibliography, you can
 use the `--max` option:
 

data/features/citation.feature

@@ -554,3 +554,38 @@ Feature: Citations
     And I should see "Flanagan" in "_site/scholar.html"
     And I should see "Gamma" in "_site/scholar.html"
 
+  @tags @cite
+  Scenario: Multiple Citations with separate links
+    Given I have a scholar configuration with:
+      | key            | value             |
+      | source         | ./_bibliography   |
+      | bibliography   | my_references     |
+      | separate_links | true              |
+    And I have a "_bibliography" directory
+    And I have a file "_bibliography/my_references.bib":
+      """
+      @book{ruby,
+        title     = {The Ruby Programming Language},
+        author    = {Flanagan, David and Matsumoto, Yukihiro},
+        year      = {2008},
+        publisher = {O'Reilly Media}
+      }
+
+      @book{microscope,
+        title     = {Ruby Under a Microscope},
+        author    = {Pat Shaughnessy},
+        year      = {2013},
+        publisher = {No Starch Press}
+      }
+      """
+    And I have a page "scholar.html":
+      """
+      ---
+      ---
+      {% cite ruby microscope %}
+      """
+    When I run jekyll
+    Then the _site directory should exist
+    And the "_site/scholar.html" file should exist
+    And I should see "\(<a.*href=\"#ruby\".*</a>; <a.*href=\"#microscope\".*</a>\)" in "_site/scholar.html"
+

data/features/grouping.feature

@@ -376,3 +376,98 @@ Feature: Grouping BibTeX Bibliographies
     Then I should see "<h2 class=\"bibliography\">2007</h2>" in "_site/scholar.html"
     And I should see "<h2 class=\"bibliography\">2008</h2>" in "_site/scholar.html"
     And "2008" should come before "2007" in "_site/scholar.html"
+
+  @tags @grouping
+  Scenario: Group By Name
+    Given I have a scholar configuration with:
+      | key      | value             |
+      | group_by | name              |
+    And I have a "_bibliography" directory
+    And I have a file "_bibliography/references.bib":
+      """
+      @book{book_by_author,
+        title     = {First Book by Adams},
+        author    = {Adams, Alice},
+        year      = {2020}
+      }
+      @book{another_by_author,
+        title     = {Second Book by Adams},
+        author    = {Adams, Alice},
+        year      = {2021}
+      }
+      @book{edited_volume,
+        title     = {Edited Collection},
+        editor    = {Baker, Bob},
+        year      = {2020}
+      }
+      @techreport{tech_report,
+        title       = {Technical Report},
+        institution = {MIT},
+        year        = {2020}
+      }
+      """
+    And I have a page "scholar.html":
+      """
+      ---
+      ---
+      {% bibliography -f references %}
+      """
+    When I run jekyll
+    Then the _site directory should exist
+    And the "_site/scholar.html" file should exist
+    Then I should see "<h2 class=\"bibliography\">Adams, Alice</h2>" in "_site/scholar.html"
+    And I should see "<h2 class=\"bibliography\">Baker, Bob</h2>" in "_site/scholar.html"
+    And I should see "<h2 class=\"bibliography\">MIT</h2>" in "_site/scholar.html"
+    And "Adams, Alice" should come before "Baker, Bob" in "_site/scholar.html"
+    And "Baker, Bob" should come before "MIT" in "_site/scholar.html"
+
+  @tags @grouping
+  Scenario: Group By Name With Sorting Within Groups
+    Given I have a scholar configuration with:
+      | key      | value             |
+      | group_by | name              |
+      | sort_by  | year              |
+    And I have a "_bibliography" directory
+    And I have a file "_bibliography/references.bib":
+      """
+      @book{adams_2021,
+        title     = {Second Book by Adams},
+        author    = {Adams, Alice},
+        year      = {2021}
+      }
+      @book{adams_2019,
+        title     = {First Book by Adams},
+        author    = {Adams, Alice},
+        year      = {2019}
+      }
+      @book{adams_2020,
+        title     = {Third Book by Adams},
+        author    = {Adams, Alice},
+        year      = {2020}
+      }
+      @book{baker_2022,
+        title     = {Recent Edited Collection},
+        editor    = {Baker, Bob},
+        year      = {2022}
+      }
+      @book{baker_2018,
+        title     = {Earlier Edited Collection},
+        editor    = {Baker, Bob},
+        year      = {2018}
+      }
+      """
+    And I have a page "scholar.html":
+      """
+      ---
+      ---
+      {% bibliography -f references %}
+      """
+    When I run jekyll
+    Then the _site directory should exist
+    And the "_site/scholar.html" file should exist
+    Then I should see "<h2 class=\"bibliography\">Adams, Alice</h2>" in "_site/scholar.html"
+    And I should see "<h2 class=\"bibliography\">Baker, Bob</h2>" in "_site/scholar.html"
+    And "Adams, Alice" should come before "Baker, Bob" in "_site/scholar.html"
+    And "2019" should come before "2020" in "_site/scholar.html"
+    And "2020" should come before "2021" in "_site/scholar.html"
+    And "2018" should come before "2022" in "_site/scholar.html"

data/features/sorting.feature

@@ -299,3 +299,105 @@ Feature: Sorting BibTeX Bibliographies
     And the "_site/scholar.html" file should exist
     Then "March 08" should come before "December 08" in "_site/scholar.html"
     And "December 08" should come before "August 07" in "_site/scholar.html"
+
+  @tags @sorting
+  Scenario: Sort By Name (Author/Editor/Institution/Organization/Publisher Fallback)
+    Given I have a scholar configuration with:
+      | key     | value |
+      | sort_by | name  |
+    And I have a "_bibliography" directory
+    And I have a file "_bibliography/references.bib":
+      """
+      @book{has_author,
+        title     = {Book by Author},
+        author    = {Zulu, Zebra},
+        year      = {2020}
+      }
+      @book{has_editor,
+        title     = {Book by Editor},
+        editor    = {Alpha, Andrew},
+        year      = {2020}
+      }
+      @book{has_both,
+        title     = {Book with Both},
+        author    = {Meyer, Maria},
+        editor    = {Yankee, Yellow},
+        year      = {2020}
+      }
+      @techreport{has_institution,
+        title       = {Technical Report},
+        institution = {MIT},
+        year        = {2020}
+      }
+      @manual{has_organization,
+        title        = {Standards Document},
+        organization = {OECD},
+        year         = {2020}
+      }
+      @misc{has_publisher,
+        title     = {Anonymous Work},
+        publisher = {Publisher House},
+        year      = {2020}
+      }
+      @misc{has_none,
+        title = {No Named Entity},
+        year  = {2020}
+      }
+      """
+    And I have a page "scholar.html":
+      """
+      ---
+      ---
+      {% bibliography -f references %}
+      """
+    When I run jekyll
+    Then the _site directory should exist
+    And the "_site/scholar.html" file should exist
+    Then "No Named Entity" should come before "Book by Editor" in "_site/scholar.html"
+    And "Book by Editor" should come before "Book with Both" in "_site/scholar.html"
+    And "Book with Both" should come before "Technical Report" in "_site/scholar.html"
+    And "Technical Report" should come before "Standards Document" in "_site/scholar.html"
+    And "Standards Document" should come before "Anonymous Work" in "_site/scholar.html"
+    And "Anonymous Work" should come before "Book by Author" in "_site/scholar.html"
+
+  @tags @sorting
+  Scenario: Sort By Name With Corporate Authors (Double Braces)
+    Given I have a scholar configuration with:
+      | key     | value |
+      | sort_by | name  |
+    And I have a "_bibliography" directory
+    And I have a file "_bibliography/references.bib":
+      """
+      @book{personal_author,
+        title     = {Book by Personal Author},
+        author    = {Smith, John},
+        year      = {2020}
+      }
+      @misc{corporate_double_brace,
+        title     = {Annual Vegetable Report},
+        author    = {{Cauliflower Appreciation Society}},
+        year      = {2020}
+      }
+      @book{personal_early,
+        title     = {Book by Early Author},
+        author    = {Baker, Bob},
+        year      = {2020}
+      }
+      @misc{corporate_early,
+        title     = {Used Kar Price Guide},
+        author    = {{Aardvark Kar Korp LTD}},
+        year      = {2020}
+      }
+      """
+    And I have a page "scholar.html":
+      """
+      ---
+      ---
+      {% bibliography -f references %}
+      """
+    When I run jekyll
+    Then the _site directory should exist
+    And the "_site/scholar.html" file should exist
+    Then "Used Kar Price Guide" should come before "Book by Early Author" in "_site/scholar.html"
+    And "Book by Early Author" should come before "Annual Vegetable Report" in "_site/scholar.html"
+    And "Annual Vegetable Report" should come before "Book by Personal Author" in "_site/scholar.html"

data/lib/jekyll/scholar/defaults.rb

@@ -60,11 +60,11 @@ module Jekyll
       # Valid template parameters:
       #    ":details_dir"   The value of the details_dir field in the scholar config
       #    ":key"           The bibtex citation key.
-      #    ":doi"           The DOI. If the DOI is missing or blank, this returns the citation key. 
+      #    ":doi"           The DOI. If the DOI is missing or blank, this returns the citation key.
       #    ":extension"     Either of ".html" or "/index.html" depending upon the global permalink setting.
       # Template parameters can also include any key defined in the bibtex file, e.g. ":year", ":title", etc.
       # Bibtex keys such as 'title' are slugified in the same way as Jekyll treats blog post titles.
-      'details_permalink'       => '/:details_dir/:key:extension', 
+      'details_permalink'       => '/:details_dir/:key:extension',
 
       'bibliography_class'     => 'bibliography',
       'bibliography_template'  => '{{reference}}',
@@ -78,6 +78,12 @@ module Jekyll
 
       'cite_class'             => 'citation',
 
+      # If true, render in-page links from in-text citations to references as separate links (one link per citation).
+      # If false, render as only one link to the first citation.
+      # Note: This feature may not work with citation styles that group in-text citations
+      # like `[1-3]` rather than `[1, 2, 3]`
+      'separate_links'         => false,
+
       'type_names' => {
         'article' => 'Journal Articles',
         'book' => 'Books',

data/lib/jekyll/scholar/utilities.rb

@@ -236,14 +236,29 @@ module Jekyll
         !offset.nil? || !max.nil?
       end
 
+      def resolve_sort_value(entry, key)
+        case key
+        when 'name'
+          # Fallback chain: author → editor → institution → organization → publisher
+          # Convert to lowercase string for case-insensitive cross-type comparison
+          # Strip leading/trailing braces and whitespace (for corporate authors like {{Name}})
+          value = entry[:author] || entry[:editor] || entry[:institution] ||
+            entry[:organization] || entry[:publisher]
+          normalized = value ? value.to_s.gsub(/\A[{\s]+|[}\s]+\z/, '').downcase : ''
+          BibTeX::Value.new(normalized)
+        else
+          entry[key].nil? ? BibTeX::Value.new : entry[key]
+        end
+      end
+
       def sort(unsorted)
         return unsorted if skip_sort?
 
         sorted = unsorted.sort do |e1, e2|
           sort_keys
             .map.with_index do |key, idx|
-            v1 = e1[key].nil? ? BibTeX::Value.new : e1[key]
-            v2 = e2[key].nil? ? BibTeX::Value.new : e2[key]
+            v1 = resolve_sort_value(e1, key)
+            v2 = resolve_sort_value(e2, key)
             if (sort_order[idx] || sort_order.last) =~ /^(desc|reverse)/i
               v2 <=> v1
             else
@@ -350,6 +365,10 @@ module Jekyll
           else
             value.to_s
           end
+        when 'name'
+          value = item[:author] || item[:editor] || item[:institution] ||
+            item[:organization] || item[:publisher] || BibTeX::Value.new
+          value.to_s
         else
           value = item[key]
           if value.numeric?
@@ -501,6 +520,30 @@ module Jekyll
         interpolate(@style)|| config['style']
       end
 
+      # The citation layout object for the currently selected style
+      # @return [CSL::Style::Layout]
+      def layout
+        styles(style).citation.layout
+      end
+
+      # Prefix string before citations. If style has no prefix, return empty string
+      # @return [String]
+      def csl_prefix
+        layout.attributes.prefix.nil? ? '' : layout.attributes.prefix
+      end
+
+      # Suffix string after citations. If style has no suffix, return empty string
+      # @return [String]
+      def csl_suffix
+        layout.attributes.suffix.nil? ? '' : layout.attributes.suffix
+      end
+
+      # Delimiter between citations in a citation group
+      # @return [String]
+      def delimiter
+        layout.delimiter
+      end
+
       def missing_reference
         config['missing_reference']
       end
@@ -742,14 +785,33 @@ module Jekyll
           if bibliography.key?(key)
             entry = bibliography[key]
             cite_cache.getset(key) do
-              entry.convert(*bibtex_filters) unless bibtex_filters.empty?
+              entry = entry.convert(*bibtex_filters) unless bibtex_filters.empty?
+
+              if config['separate_links']
+                ## Render each citation in the group as a separate link
+                # Render the single citation, stripping delimiting characters
+                rendered = render_citation([entry])
+                  .sub(/^#{Regexp.escape(csl_prefix)}/, '')
+                  .sub(/#{Regexp.escape(csl_suffix)}$/, '')
+
+                # Then render to HTML with the link to this specific citation
+                link_to link_target_for(key), rendered, {class: config['cite_class']}
+              else
+                entry
+              end
             end
           else
             return missing_reference
           end
         end
 
-        link_to link_target_for(keys[0]), render_citation(items), {class: config['cite_class']}
+        if config['separate_links']
+          # Combine individual linkified items
+          csl_prefix + items.join(delimiter) + csl_suffix
+        else
+          # Render as a single link
+          link_to link_target_for(keys[0]), render_citation(items), {class: config['cite_class']}
+        end
       end
 
       def nocite(keys)
@@ -828,6 +890,7 @@ module Jekyll
         self
       end
 
+      # @return [CSL::Style]
       def load_style(uri)
         begin
           style = CSL::Style.load uri
@@ -847,6 +910,8 @@ module Jekyll
         end
       end
 
+      # Access or load style by style URI or relative path
+      # @return [CSL::Style]
       def styles(style)
         STYLES[style] ||= load_style(style)
       end

data/lib/jekyll/scholar/version.rb

@@ -1,5 +1,5 @@
 module Jekyll
   class Scholar
-    VERSION = '7.2.3'.freeze
+    VERSION = '7.3.0'.freeze
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-scholar
 version: !ruby/object:Gem::Version
-  version: 7.2.3
+  version: 7.3.0
 platform: ruby
 authors:
 - Sylvester Keil
 bindir: bin
 cert_chain: []
-date: 2025-12-04 00:00:00.000000000 Z
+date: 2026-01-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll