Individual cite links (#363)

* initial draft of separate citation links

* make separating links optional, add single test

* fix tests that were broken by csl style changes

Author: sneakers-the-rat

README.md

@@ -73,6 +73,7 @@ description of all options and their defaults, see
 | `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

features/bibtex.feature

@@ -524,7 +524,7 @@ Feature: BibTeX
       | source                 | ./_bibliography               |
       | bibliography           | my_references                 |
       | allow_locale_overrides | true                          |
-      | style                  | chicago-fullnote-bibliography |
+      | style                  | chicago-notes-bibliography |
     And I have a "_bibliography" directory
     And I have a file "_bibliography/my_references.bib":
       """

features/citation.feature

@@ -352,7 +352,7 @@ Feature: Citations
     When I run jekyll
     Then the _site directory should exist
     And the "_site/scholar.html" file should exist
-    And I should see "Matsumoto, 2008, Chapters 2-3; Shaughnessy, 2013, figs. 4,5" in "_site/scholar.html"
+    And I should see "Matsumoto, 2008, Chapters 2-3; Shaughnessy, 2013, Figures 4,5" in "_site/scholar.html"
 
   @tags @cite @locator @label
   Scenario: Citations with multiple locator labels
@@ -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"
+

lib/jekyll/scholar/defaults.rb

@@ -60,11 +60,11 @@ class Scholar
       # 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 @@ class Scholar
 
       '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',

lib/jekyll/scholar/utilities.rb

@@ -501,6 +501,30 @@ def style
         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 +766,33 @@ def cite(keys)
           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 +871,7 @@ def set_context_to(context)
         self
       end
 
+      # @return [CSL::Style]
       def load_style(uri)
         begin
           style = CSL::Style.load uri
@@ -847,6 +891,8 @@ def load_style(uri)
         end
       end
 
+      # Access or load style by style URI or relative path
+      # @return [CSL::Style]
       def styles(style)
         STYLES[style] ||= load_style(style)
       end