Skip to content

GitLab

Commit fd1c3435 authored by Ellis Michael's avatar Ellis Michael Committed by Sylvester Keil
Browse files

Referencing defaults.rb from README, added table (#178) 

The README now explicitly says it only contains some of the configuration
and that the others are in defaults.rb. Config options are listed in a
table.
parent de618cc5
Hide whitespace changes
Inline Side-by-side
Showing with 35 additions and 84 deletions
README.md
View file @ fd1c3435
......@@ -53,92 +53,32 @@ configuration:
gems: ['jekyll/scholar']
In your configuration you can now adjust the Jekyll-Scholar settings. The
default configuration is as follows:
### Configuration
In your Jekyll configuration file you can adjust the Jekyll-Scholar settings
using the `scholar` key. For example, the following sets the bibliography style
to `mla`.
scholar:
style: apa
locale: en
sort_by: none
order: ascending
group_by: none
group_order: ascending
source: ./_bibliography
bibliography: references.bib
bibliography_template: "{{reference}}"
replace_strings: true
join_strings: true
use_raw_bibtex_entry: true
bibtex_filters:
- superscript
- latex
details_dir: bibliography
details_layout: bibtex.html
details_link: Details
query: "@*"
You can use any style that ships with
[CiteProc-Ruby](https://github.com/inukshuk/citeproc-ruby) by name (e.g.,
apa, mla, chicago-fullnote-bibliography) which is usually the filename as seen
[here](https://github.com/citation-style-language/styles)
sans the `.csl` ending; note that you have to use `dependent/style` if you want
to use one from that directory.
Alternatively you can add a link to any CSL style (e.g., you could link to any of the styles available at
the official [CSL style repository](https://github.com/citation-style-language/styles)).
The `locale` settings defines what language to use when formatting
your references (this typically applies to localized terms, e.g., 'Eds.' for
editors in English).
The `source` option indicates where your bibliographies are stored;
`bibliography` is the name of your default bibliography. For best results,
please ensure that your Bibliography is encoded as ASCII or UTF-8.
The `use_raw_bibtex_entry` option by default disable parsing of Liquid tags
embedded in the Bibtex fields. This option provides a way to circumvent the
problem that (the conflicting syntax of) the double braces functionality of
BibTex is accidentally parsed by Liquid, while it was intended to keep the
exact capitalization style.
The `sort_by` and `order` options specify if and how bibliography
entries are sorted. Entries can be sorted on multiple fields, by using
a list of keys, e.g. `sort_by: 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.
The `group_by` and `group_order` options specify how bibliography
items are grouped. Grouping can be multi-level as well,
e.g. `group_by: type, year` groups entries per publication type, and
within those groups per year. 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 }`.
The `bibtex_filters` option configures which
[BibTeX-Ruby](https://github.com/inukshuk/bibtex-ruby) formatting filters
values of entries should be passed through. This defaults to the `latex`
filter which converts LaTeX character escapes into unicode, and `superscript`
which converts the `\textsuperscript` command into a HTML `<sup>` tag.
style: mla
The table below describes some commonly used configuration options. For a
description of all options and their defaults, see
[`defaults.rb`](/lib/jekyll/scholar/defaults.rb).
| Option | Default | Description |
|--------|---------|-------------|
| `style` | `apa` | Indicates the style used for the bibliography and citations. You can use any style that ships with [CiteProc-Ruby](https://github.com/inukshuk/citeproc-ruby) by name (e.g., apa, mla, chicago-fullnote-bibliography) which is usually the filename as seen [here](https://github.com/citation-style-language/styles) without the `.csl` ending; note that you have to use `dependent/style` if you want to use one from that directory. Alternatively you can add a link to any CSL style (e.g., you could link to any of the styles available at the official [CSL style repository](https://github.com/citation-style-language/styles)). |
| `locale` | `en` | Defines what language to use when formatting your references (this typically applies to localized terms, e.g., 'Eds.' for editors in English). |
| `source` | `./_bibliography` | Indicates where your bibliographies are stored. |
| `bibliograpy` | `references.bib` | Indicates the name of your default bibliography. For best results, please ensure that your bibliography is encoded as ASCII or UTF-8. |
| `use_raw_bibtex_entry` | `true` | When `true`, disables parsing of Liquid tags embedded in the Bibtex fields. This option provides a way to circumvent the problem that (the conflicting syntax of) the double braces functionality of BibTex is accidentally parsed by Liquid, while it was intended to keep the exact capitalization style. |
| `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. |
| `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,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, and `superscript` which converts the `\textsuperscript` command into a HTML `<sup>` tag. |
### Bibliographies
......
lib/jekyll/scholar/defaults.rb
View file @ fd1c3435
module Jekyll
class Scholar
@defaults = {
# Style used for citations and bibliographies
'style' => 'apa',
# Sets languages used in bibliography
'locale' => 'en',
# Keys used to sort bibliography
'sort_by' => 'none',
# Order used to sort biobliography
'order' => 'ascending',
'group_by' => 'none',
'group_order' => 'ascending',
# HTML tags used for bibliography group names
'bibliography_group_tag' => 'h2,h3,h4,h5',
# HTML tag used for list of bibliography entries
'bibliography_list_tag' => 'ol',
# HTML tag used for individual bibliography entries
'bibliography_item_tag' => 'li',
# Attributes applied to HTML tag for list of bibliography entries
'bibliography_list_attributes' => {},
# Attributes applied to HTML tag for bibliography entries
'bibliography_item_attributes' => {},
# Name of folder references files are stored in
'source' => './_bibliography',
# Name of default references file
'bibliography' => 'references.bib',
'repository' => nil,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment