No commit activity in last 3 years
No release in over 3 years
A middleman extension that gives helpers for creating citations using citeproc
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies
 Project Readme

Middleman-citation

Codeship Status for gabysbrain/middleman-citation

This is an extension for the Middleman static site generator that adds functions you can use in your templates for formating citations from BibTeX.

An example of a Middleman template using this plugin is available at https://github.com/gabysbrain/website/blob/master/source/cv.html.slim.

Installation

Add this line to your Gemfile:

gem 'middleman-citation'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install middleman-citation

Configuration

In your config.rb file for your site add:

require 'middleman-citation'

activate :citation do |opts|
  opts.bibtex = '/path/to/your.bib' # path to a bibtex file
  opts.style  = 'ieee'              # style from citeproc-styles
  opts.format = 'html'              # output format
end

Usage

This adds the following helper methods you can use in your Middleman templates.

  • citations_search(search_term, author): Search the BibTeX file for all citations matching a search term (such as '@article') and by the given author. The author argument can be ommitted to match all authors and a search_term of nil will match all items in the bibliography.

  • citation(key): Given a BibTeX citation key as returned from citations_search, return a formatted string the citation according to how the style and format options were set.

For extra control on the output, one can use:

  • citation_entry(key): Return the unformatted entry (a hash) corresponding to the BibTeX citation key.

  • citation_formatted(entry): Format an unformatted entry.

In fact the citation method is implemented using these:

def citation(key)
  entry = citation_entry(key)
  citation_formatted(entry)
end

The point is that one can interrogate the unformatted entry to add extra formatting: The following code adds a DOI link if the entry matching the key has a URL field containing the DOI.

entry      = citation_entry(key)
entry_html = citation_formatted(entry)
if doi_url = entry.fetch('URL', false) then
  doi_link = "(%s)" % link_to('doi', doi_url)
end
[entry_html, doi_link].compact.join(' ')

Contributing

  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request