https://github.com/bcdavasconcelos/citetools
📚 This extension introduces advanced bibliography features to Pandoc and Quarto's Citeproc environment. It bundles several Lua filters to address complex bibliography demands while keeping the output consistent across all formats (`LaTeX`, `DOCX`, `HTML`, and so on).
https://github.com/bcdavasconcelos/citetools
bibliography bibtex citeproc csl-json pandoc-filters quarto-filter
Last synced: 8 months ago
JSON representation
📚 This extension introduces advanced bibliography features to Pandoc and Quarto's Citeproc environment. It bundles several Lua filters to address complex bibliography demands while keeping the output consistent across all formats (`LaTeX`, `DOCX`, `HTML`, and so on).
- Host: GitHub
- URL: https://github.com/bcdavasconcelos/citetools
- Owner: bcdavasconcelos
- License: mit
- Created: 2023-03-18T07:06:35.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2023-12-21T21:51:00.000Z (over 2 years ago)
- Last Synced: 2023-12-21T22:35:41.061Z (over 2 years ago)
- Topics: bibliography, bibtex, citeproc, csl-json, pandoc-filters, quarto-filter
- Language: Lua
- Homepage: https://bcdavasconcelos.github.io/citetools/docs_qmd/03-cite-field.html
- Size: 15 MB
- Stars: 14
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: changelog.md
- License: LICENSE
Awesome Lists containing this project
README
# 📚 Cite Tools for Pandoc and Quarto
[](https://github.com/bcdavasconcelos/citetools/actions/workflows/quarto-publish.yml)
This extension introduces advanced bibliography features to Pandoc and Quarto's Citeproc environment. It bundles several Lua filters ([*vide infra*](#license)) to address complex bibliography demands while keeping the output consistent across all formats (`LaTeX`, `DOCX`, `HTML`, and so on).
## Features
More specifically, this bunddle seeks to address in the simplest of ways possible the following demands:
**1. Multiple bibliographies**
The need for multiple bibliographies (or bibliographies with multiple sections, such as `primary sources` and `secondary sources`).
**2. Cite fields**
The need to evoke arbitrary information from the references, such as `author`, `editor`, or `translator` names and `title` / `original-title` of works.
`@AristOp` in `csljson`
```json
{
"author": [
{
"family": "Aristotle"
}
],
"editor": [
{
"family": "Bekker",
"given": "Immanuel"
}
],
"id": "AristOp",
"issued": {
"date-parts": [
[
1831
]
]
},
"number-of-volumes": "4",
"publisher": "Reimer",
"publisher-place": "Berlim",
"title": "Aristotelis opera",
"type": "book"
}
```
**3. Citation backlinks**
The need to turn the bibliography into a linked index of cited references, with links from the entries back to each of its multiple occurences in the body of the text (*e.g.* in `PDF`/`DOCX`: `[p. 1, p. 4, p. 10]`, in `HTML`: `[1, 2, 3]`) (and with the ability to turn these off globally or in an *ad hoc* fashion).
- *Optionally*, the need to split the bibliography into sections, printing the bibliography for each chapter/section/part. (For this, you must uncomment the apropriate line in the `_extension.yaml` file.)
## Install
Users of Quarto can install this extension with the following command
```bash
quarto install extension bcdavasconcelos/citetools
```
and use it by adding `citetools` to the `filters` entry in their YAML header.
``` yaml
---
filters:
- citetools
---
```
## Configuration
### Multiple bibliographies
Add bibliography files to the `refs` folder. Then, add the following metadata to the YAML header of your document in this way:
```yaml
---
bibliography_primary: refs/primary.json
bibliography_secondary: refs/secondary.json
---
```
Then, place the bibliographies placeholders in the document where you want the bibliographies to appear.
``` markdown
# Primary Sources
::: {#refs_primary}
:::
# Secondary Sources
::: {#refs_secondary}
:::
```
These divs are filled with citations from the respective bib-file. Each refs-*x* div should have a matching entry *x* in the metadata.
**Make sure the bibliography name and the placeholder div id match.**
That is, if you have a bibliography named `bibliography_primary`, the placeholder div should be `refs-primary` or `refs_primary`.
### Cite fields and citation backlinks global options
- `link-fields` (boolean): Link inlines printed by `citefield` to their corresponding entry in the bibliography. Default: `true`.
- `link-citations` (boolean): Link citations to their respective reference in the bibliography. Default: `true`. Note: if `link-citations` is set to `false`, `link-fields` is also set to `false`.
---
See sample document `sample.qmd` for a working example with explanations.
