-
Notifications
You must be signed in to change notification settings - Fork 1
/
index.qmd
144 lines (96 loc) · 8.11 KB
/
index.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
---
title: |
Cite Tools
subtitle: |
Advanced bibliography for Pandoc <img src="https://avatars.githubusercontent.com/u/110831952?s=200&v=4" style="object-fit: cover;width:1em;height:1em;" /> and Quarto <img id="top" src="https://quarto.org/favicon.png" style="object-fit: cover;width:1em;height:1em;" />
author: "Bernardo Vasconcelos"
date: 2023-03-26
filters:
- citetools
# - fontawesome
---
Cite Tools is an extension of the Quarto Open-Source Scientific and Technical Publishing System, built upon Pandoc and compatible with any version above `2.17`, that bundles together [several Lua filters](/docs_qmd/05-about.qmd) 🌙 to introduce advanced bibliography features.
## Why a bibliography extension?
Users of the jurassic [BibTeX](https://en.wikipedia.org/wiki/BibTeX) would probably be exceptionally pleased with the speed and reliability of Pandoc Citeproc. Apart from being (*a lot*) faster, Citeproc will produce the same output across all formats supported by Pandoc, which amount to over 60, including HTML, LaTeX, and Word.
Out-of-the-box, however, Citeproc does not provide common BibTeX functionalities, such as the ability to split the bibliography into multiple sections, or the ability to cite arbitrary fields of the references (*e.g.* `citetitle`, `citeauthor`, `citefield`). It also lacks the interesting **backref** option afforded by BibTeX and [HyperRef](http://www.ctan.org/pkg/hyperref), which allows for the creation of linked indexes of citations.
Luckily, Citeproc is extensible, and this extension aims to provide a solution to these limitations and, *hopefully*, allow Pandoc and Quarto users to **completely** replace BibTeX/BibLaTeX with Citeproc. It will allow the user to *easily* create multiple bibliographies (or bibliographies with multiple sections, such as *primary* and *secondary sources*), cite arbitrary fields of the references^[In the official nomenclature, CSL has *variables*, BibTeX has *fields*, and RIS has *tags*. As a general rule, we have stuck to the term *fields*.], and create linked indexes of citations^[Linked glossaries can also easily be created by dressing it as bibiography]. All of this with very little configuration needed.
Also, with the advent of Quarto, it has become easier for those not well-versed Lua or Pandoc to use extensions such as this one! So, why not?!
## New to Quarto <img src="https://quarto.org/favicon.png" style="object-fit: cover;width:1em;height:1em;" />?
Quarto is an open-source scientific and technical publishing system. Visit the [getting started](https://quarto.org/docs/get-started/) guide to download and install. Once installed, you can use it to create, build, and preview your documents.
::: {.callout-tip appearance="simple"}
**I highly recommend visiting the [Tutorial: Hello, Quarto](https://quarto.org/docs/get-started/hello/vscode.html).** You'll learn how to create a document, build it, and preview it. You will also be taken to the excellent extensions for [VS Code](https://quarto.org/docs/get-started/#quarto-for-vs-code) and [RStudio](https://quarto.org/docs/get-started/#quarto-for-rstudio) that will make your life easier.
:::
::: {.callout-note collapse="true"}
## Quarto Quickstart 🚀
- On macOS ({{< fa brands apple >}}), use [Homebrew](https://brew.sh/) to `brew install quarto`.
- On Windows ({{< fa brands windows >}}), use [Chocolatey](https://chocolatey.org/) to `choco install quarto`.
- On Linux ({{< fa brands linux >}}), use your package manager to install `quarto`.
Find out more at [Awesome Quarto](https://github.com/mcanouil/awesome-quarto), [Quarto Extensions](https://github.com/quarto-ext?type=source), [Quarto on Github](https://github.com/search?q=topic%3Aquarto&type=repositories), [RStudio Community](https://community.rstudio.com/tags/quarto), [Stack Overflow](https://stackoverflow.com/questions/tagged/quarto), [Twitter](https://twitter.com/quarto_pub).
:::
## New to Pandoc <img src="https://avatars.githubusercontent.com/u/110831952?s=200&v=4" style="object-fit: cover;width:1em;height:1em;" />?
[Pandoc](https://pandoc.org/) is a universal document converter developed by John MacFarlane, professor of philosophy, that is at the core of Quarto. To learn more about it, see the [Pandoc User's Guide](https://pandoc.org/MANUAL.html) [{{< fa regular file-pdf >}}](https://pandoc.org/MANUAL.pdf). You can install Pandoc as a standalone application, but it will also inevitably be included in any Quarto instalation.
Make sure to check [Pandoc-Discuss](https://groups.google.com/g/pandoc-discuss) in case you have unsolved questions. You can also ask questions on [Pandoc at Stack Overflow](https://stackoverflow.com/questions/tagged/pandoc).
## Installation 📦
If the prospect of typing something on the command line seems daunting, or if you simply need a sample, you can download the [citetools repository](https://github.com/bcdavasconcelos/citetools/archive/refs/heads/main.zip) {{< fa brands github >}} directly and open it in VSCode to see a working example.
Otherwise, create a new project and install it using:
```bash
quarto install extension bcdavasconcelos/citetools
```
Activate it by adding `citetools` to the `_quarto.yml` file in the filters section.
```yaml
filters:
- citetools
```
## Quickstart 🚀
Add the path to the bibliography files to the document YAML header or `_quarto.yml` 📁
```yaml
---
bibliography_bib-name: path/to/bibfile.bib
bibliography_other-bib-name: path/to/otherbibfile.bib
---
```
Place the corresponding placeholders where they should be printed in the document body 🖨️
```markdown
::: {#refs_bib-name}
:::
::: {#refs_other-bib-name}
:::
```
You're ready to rock. 🤘
## Usage 📖
Cite references [as you normally do in Pandoc](/docs_qmd/01-basics.qmd#how-to-cite-in-pandoc) and they will be linked 🔗 and backlinked 🔗 to the bibliography 📚
```markdown
[@citekey]
```
Use `[@Citekey]{.csl_field}` to arbitrarily print specific fields instead of the usual Author-Date format. This is useful for printing the title of a book or the name of a journal in the text. 🎯
```markdown
[@citekey]{.author}
[@citekey]{.title}
[@citekey]{.original-title}
```
Append the field name with a dot to avoid creating a link to the bibliography in this particular citation📍
```markdown
[@citekey]{.author.}
```
This can also be done globally 🌐 by setting `link-fields: false` in the metadata^[If `link-citations` is `false` then `link-fields` will also default to `false`.]. This is useful if you want to print the title of a book or the name of a journal in the text, but don't want to create a link to the bibliography.
```yaml
---
link-fields: false
---
```
## Documentation 📚
This [Quarto-powered website](https://quarto.org/docs/websites/) provides documentation for the following filters:
- [{{< fa solid file-code >}}](https://github.com/bcdavasconcelos/citetools/blob/main/_extensions/citetools/multiple-bibliographies.lua) [multiple-bibliographies](/docs_qmd/02-multibib.qmd)
- [{{< fa solid file-code >}}](https://github.com/bcdavasconcelos/citetools/blob/main/_extensions/citetools/cite-field.lua) [cite-field](/docs_qmd/03-cite-field.qmd)
- [{{< fa solid file-code >}}](https://github.com/bcdavasconcelos/citetools/blob/main/_extensions/citetools/citation-backlinks.lua) [citation-backlinks](/docs_qmd/04-citation-backlinks.qmd)
In the future, we plan to add documentation for the following filters:
- [section-bibliographies](https://github.com/pandoc-ext/section-bibliographies)
- [recursive citeproc](https://github.com/dialoa/recursive-citeproc)
## Contributing 🤝
If you have suggestions for other filters, improvements to the existing ones, or bug reports, please open an issue at the [citetools repository](https://github.com/bcdavasconcelos/citetools/issues) {{< fa brands github >}}.
## Acknowledgments 🙏
- Albert Krewinkel, for creating Pandoc filters.
- John MacFarlane, for creating Pandoc.
- The community of Quarto and Pandoc developers and users.
## See also
- [ScriQ](https://github.com/bcdavasconcelos/ScrivQ/) is a Scrivener template with hundreds of built-in Quarto parameters, plus the ability to export multiple files, to handle cross-references and manage bibliography.