Citations and references

tw cite maintains a reference library: the books and articles you cite. A reference can be added from its DOI or ISBN, imported from other programs, formatted in a citation style such as APA or MLA, and checked against a manuscript to confirm that every citation resolves to a reference in the library. The command is intended for students and writers who work by keyboard and speech, and every message is a complete sentence, so that it reads well with a screen reader or with textweaver's own voice. Citations in your writing use Pandoc's Markdown syntax, such as [@doe2020, p. 12], so the same files work with Pandoc and other academic tools.

Prerequisites

tw, which is included with textweaver. See the install guide.
An internet connection the first time you add a reference by DOI or ISBN; everything else works offline.
No other software: neither Pandoc nor Zotero is needed.

What a reference library is

A reference library is a single file, references.json, that holds your references in CSL-JSON, the format used by Zotero, Pandoc, and doi.org. It can be opened in any text editor, and Pandoc can read it directly.

textweaver uses two kinds of library:

Your personal library is references.json in textweaver's data folder. Every tw cite command uses it unless you say otherwise.
A folder library is references.json inside a folder of documents, such as a folder for one essay or one course. It keeps a project self-contained: copy the folder, and its references go with it. Choose it with --folder FOLDER.

When tw cite format or tw cite check looks up a key, it searches the folder library first and your personal library second. A folder library can therefore hold only one project's references and still draw on the rest of your personal library. The other commands (add, import, export, list, and remove) work on the folder library alone.

Any library file can also be used with --library FILE; like a folder library, it is searched first, and your personal library second, when formatting and checking. --folder and --library cannot be combined.

The personal library is in these places:

Windows: %APPDATA%\leavesofgrass\textweaver\data\references.json
macOS: ~/Library/Application Support/org.leavesofgrass.textweaver/references.json
Linux: ~/.local/share/textweaver/references.json
When the TEXTWEAVER_HOME environment variable is set: data\references.json inside that folder.

The file is created the first time a reference is added or imported.

Find your library

tw cite list

This lists every reference and states where the library file is. When the library is empty, you hear, for example:

The reference library at C:\Users\you\AppData\Roaming\leavesofgrass\textweaver\data\references.json is empty. Add references with tw cite add or tw cite import.

To see a folder library instead, add --folder and the folder:

tw cite list --folder "Biology essay"

The --folder and --library options may precede or follow the command name, so tw cite --folder "Biology essay" list works too.

Add a reference by DOI

tw cite add 10.1038/nature12373

A DOI (digital object identifier) is the identifier printed on most journal articles, such as 10.1038/nature12373. It may be typed in any of these forms:

10.1038/nature12373
doi:10.1038/nature12373
https://doi.org/10.1038/nature12373
https://dx.doi.org/10.1038/nature12373

textweaver asks doi.org for the reference and adds it. This works for DOIs registered with Crossref, DataCite, and mEDRA, so datasets and theses are covered as well as journal articles. When the reference is added you hear one sentence, such as this real one:

Added reference kucsko2013. Kucsko and others, 2013. Nanometre-scale thermometry in a living cell. Key kucsko2013.

The first part reports that the reference was added and gives its citation key (here kucsko2013); the rest describes the reference itself: authors, year, title, and key. Three or more authors are read as "and others".

If the same work is already in the library, it is updated rather than added twice:

Updated reference kucsko2013, which was already in the library. Kucsko and others, 2013. Nanometre-scale thermometry in a living cell. Key kucsko2013.

What is sent over the network

Only the DOI is sent. textweaver makes one secure (HTTPS) request to https://doi.org/ followed by the DOI and asks for the answer as CSL-JSON. The request identifies itself as coming from textweaver; no file, name, or other information about you is sent.

Wait longer for a slow connection

tw cite add 10.1038/nature12373 --timeout 30

By default textweaver waits 15 seconds for an answer; --timeout sets the number of seconds.

Add a book by ISBN

tw cite add 978-0-306-40615-7

An ISBN (International Standard Book Number) is the number printed on the back of a book, with 10 or 13 digits. It may be typed with or without hyphens and spaces, and with or without ISBN in front, for example ISBN 0-306-40615-2.

Before contacting any service, textweaver verifies the last digit, which is a check digit, so a mistyped digit is caught at once without using the network.

Books are looked up in Open Library (openlibrary.org). textweaver requests the edition record for the ISBN and, if there is none, tries the other form of the same ISBN (10 or 13 digits). It then requests the authors' records to obtain their names, for up to ten authors. Only the ISBN and Open Library's own record numbers are sent. A real result:

Added reference clark1981. Clark, 1981. Error-correction coding for digital communications. Key clark1981.

Lookups, the cache, and working offline

Every answer from doi.org or Open Library is saved in a cache folder. When you add the same DOI or ISBN again, the answer comes from the cache without any network use, so a reference you have looked up once can be added again offline, for example to a folder library.

The cache is the citations folder inside textweaver's cache folder:

Windows: %LOCALAPPDATA%\leavesofgrass\textweaver\cache\citations
macOS: ~/Library/Caches/org.leavesofgrass.textweaver/citations
Linux: ~/.cache/textweaver/citations
With TEXTWEAVER_HOME set: cache\citations inside that folder.

The cache keeps the newest 500 answers and discards older ones; the folder can be deleted at any time without harm.

When a lookup fails, nothing is added to the library, and the message says so. The messages are as follows, with your DOI or ISBN in place of the examples:

Not connected: "Could not reach doi.org. You may be offline; nothing was added. Try again when you are connected." Technical details follow the word "Details".
Too slow: "doi.org did not answer within 15 seconds. Nothing was added; try again later."
Unknown to the service: "doi.org has no record for DOI 10.9999/example. Nothing was added."
The service had a problem: "Open Library answered with an error, status 503. Nothing was added; try again later."
An unreadable answer: "Open Library sent an answer textweaver could not read:" then the reason, then "Nothing was added."
Not a DOI: "10.abc is not a DOI. A DOI starts with 10, then a dot, and contains a slash, for example 10.1038/nature12373."
An invalid ISBN: "978-0-306-40615-8 is not a valid ISBN. An ISBN has 10 or 13 digits, and the last one is a check digit; check for a mistyped digit."
Neither: "hello is neither a DOI nor an ISBN. Give a DOI such as 10.1038/nature12373, or a 10 or 13 digit ISBN."

Each message names the service: doi.org for DOIs, Open Library for ISBNs.

Import references from another program

tw cite import references.bib

This adds every reference in a file to your library. textweaver reads three formats:

BibTeX and BibLaTeX: files ending in .bib or .bibtex. LaTeX accents such as M{\"u}ller become the corresponding letters.
RIS: files ending in .ris. Zotero, Mendeley, EndNote, and most library catalogs can export RIS.
CSL-JSON: files ending in .json, which Zotero calls "CSL JSON".

If the file has another ending, textweaver inspects its contents to determine the format. If it still cannot tell, you hear: "Could not tell what kind of reference file notes.txt is. Use a .bib, .ris, or .json file."

When the import finishes, you hear how many references were new and how many were updated:

Imported 2 references: 2 new, 0 updated.

Importing the same file again creates no copies. Two references are the same work when they share a DOI, share an ISBN, or share both key and title, and the existing entry is updated with the new file's details.

A different work whose key is already taken receives a new key, and the message says so:

Imported 1 reference: 1 new, 0 updated. Key doe2020 was taken, so the new reference is doe2020a.

Keys in the file are kept; references without a key are given one, as described in Citation keys.

To import into a folder library, add --folder:

tw cite import references.bib --folder "Biology essay"

Export references

tw cite export --to bibtex

This prints the whole library as BibTeX. --to accepts one of these formats:

bibtex (also bib)
biblatex
ris
csl-json (also json)

To write a file instead of printing, add --out (or -o) and a file name:

tw cite export --to ris --out references.ris

You hear, for example: "Exported the references as RIS to references.ris."

To export only some references, give their keys:

tw cite export --to biblatex doe2020 muller2019

A key that is not in the library stops the export with "The citation key nobody is not in the reference library."

List your references

tw cite list

This reports the number of references and the location of the library, then gives one line per reference, sorted by author, then year, then title:

2 references in C:\Users\you\AppData\Roaming\leavesofgrass\textweaver\data\references.json:
Doe and Roe, 2020. Reading Machines. Key doe2020.
Müller, 2019. Listening to Tables. Key muller2019.

Each line is a sentence giving authors, year, title, and key; a reference with no date says "no date".

To obtain the library as CSL-JSON instead, for use by another program:

tw cite list --json

Remove a reference

tw cite remove doe2020a

The command first asks for confirmation with a yes or no; --yes (or -y) skips the question, as a script requires. It then removes the reference with that key and reports which one it was:

Removed reference doe2020a: Doe, 2020. A Different Book. Key doe2020a.

Format references with a citation style

tw cite format --style mla

This formats every reference in the library in a citation style. Each reference yields its bibliography entry, followed by the in-text citation on a line beginning "In text:". A real result for one key:

tw cite format doe2020 --style mla

Doe, Jane, and Rick Roe. Reading Machines. Accessible Press, 2020.
In text: (Doe and Roe)

Naming keys restricts the output to those references; with no keys, every reference is formatted. The default style is APA.

In a note style, such as chicago-notes, the second line begins "Note:" and holds the footnote:

Doe, Jane, and Rick Roe. Reading Machines. Accessible Press, 2020.
Note: Jane Doe and Rick Roe, Reading Machines (Accessible Press, 2020).

Each reference is formatted as if it were cited alone, so in a numbered style such as IEEE or Vancouver every in-text citation is [1]. For a properly numbered list, use --bibliography, described below.

Choose a style

These short names are built in:

apa: APA Style 7th edition (the default)
mla: MLA Handbook 9th edition
chicago: Chicago Manual of Style 18th edition, author-date
chicago-notes: Chicago Manual of Style 18th edition, notes and bibliography
harvard: Cite Them Right 12th edition, the Harvard style
ieee: IEEE Reference Guide
vancouver: Elsevier's NLM Vancouver style, numbered
ama: AMA Manual of Style 11th edition
nature: Nature

About 80 styles are built in altogether. To list all of them, one per line, with their full titles:

tw cite styles

Each line begins with the name to give to --style, for example american-chemical-society: ACS Guide 2022 revision.

You can also supply the path of a .csl style file, such as one from the Zotero style repository:

tw cite format --style "my-university.csl"

An unknown name gives: "There is no built-in citation style called nope. Try apa, mla, chicago, ieee, or vancouver, or give the path to a .csl file."

Choose plain text, Markdown, or HTML

tw cite format --bibliography --as markdown

--as chooses the markup:

plain (the default): plain text with no markup; italics are simply omitted. This is best for listening.
markdown: italics as *Reading Machines* and links in angle brackets, ready to paste into a Markdown document.
html: HTML, with <i> for italics and & for the ampersand, ready for a web page.

In Markdown and HTML, entries are separated by a blank line.

Only the in-text citation, or only the bibliography

tw cite format doe2020 muller2019 --citation

--citation prints a single in-text citation covering all the keys. In APA, for two real references:

(Clark, 1981; Kucsko et al., 2013)

In Vancouver, the same two keys give [1,2].

tw cite format --style vancouver --bibliography

--bibliography prints only the bibliography entries. In a numbered style they are numbered in order:

[1] Clark GC. Error-correction coding for digital communications. New York: Plenum Press; 1981.
[2] Kucsko G, Maurer PC, Yao NY, Kubo M, Noh HJ, Lo PK, et al. Nanometre-scale thermometry in a living cell. Nature 2013;500:54–8. https://doi.org/10.1038/nature12373.

You cannot give --citation and --bibliography together.

Numbers such as [1] are always bracketed, even in styles that print them raised, so a screen reader never runs a number into the preceding word.

Citation keys

A citation key is the short name you type to cite a work, such as doe2020. textweaver generates keys by these rules:

The first author's family name in lowercase, followed by the year: doe2020.
Accented Latin letters become plain letters, and spaces and punctuation are dropped: Müller becomes muller2019, and Van Gogh becomes vangogh1888.
With no author or editor, the first title word longer than three letters is used, skipping words such as "the", "and", and "with"; "The Accessible Classroom" from 2021 becomes accessible2021.
With neither, the key starts with ref.

When a different work already uses a key, a letter is appended: doe2020a, then doe2020b, and so on to z, after which a number is appended: doe2020-2.

Keys read aloud naturally, for example "doe twenty twenty". Keys from an imported file are kept as they are.

Write citations in Markdown

textweaver understands the citation syntax of Pandoc's Markdown, in which a key follows an @ sign. The forms are:

[@doe2020]: a plain citation, such as "(Doe & Roe, 2020)" in APA.
[@doe2020, p. 12]: a citation with a page.
[see @doe2020, pp. 33-35, emphasis added]: text before the key ("see"), a page range, and text after it.
[@doe2020; @muller2019]: two works in one citation, separated by a semicolon. Each part holds exactly one key.
@doe2020 [p. 3]: a citation that is part of your sentence, as in "Doe and Roe (2020, p. 3) show that...". The @ must come at the start of a line, or after a space or opening punctuation.
[-@doe2020]: a minus sign before the @ omits the author, for when you have already named them: "Doe and Roe agree (2020)".
@{odd key}: braces around a key that contains unusual characters.

The part after the key can name a page or another division. The most useful labels are:

p. and pp.: page and pages. A bare number is a page, so [@doe2020, 12] means page 12.
chap.: chapter
sec. or §: section
para. or ¶: paragraph
fig.: figure
vol.: volume
l. and ll.: line and lines
n.: note

Full words such as page, chapter, and section also work, and braces keep an unusual value together: [@doe2020, p. {iv, 34-37}].

The following are not citations:

An email address such as ada@example.com.
An escaped bracket: \[@doe2020].
A link: [@doe2020](https://example.com).

Punctuation immediately after a key is not part of it, so in "as @doe2020." the key ends before the period.

Check a document's citations

tw cite check essay.md

This finds every citation in a Markdown or text document and checks each key against your library; with --folder, it checks the folder library first and then your personal library. You hear one sentence, for example:

5 citations found. One key is not in the library: smith1999.

When every key is present it says "Every key is in the library.", and when the document has no citations it says "The document has no citations." To resolve a missing key, add the reference with tw cite add or tw cite import, or correct the key's spelling in your document.

See citations in converted documents

tw convert essay.md --to html --style apa

tw convert formats your citations in a citation style and adds a References section listing every work you cited. It does so for web pages, Word, PDF, EPUB, braille, and plain text; Markdown output keeps your citations as you wrote them. Pandoc is not required. A real conversion to plain text:

The area of a circle is $\pi r^2$ (see Doe, 2020, p. 12). As Müller (2019, p. 40) argues, reading aloud helps (2020).

References

Doe, J. (2020). Reading by ear. Example Press.

Müller, A. (2019). Speech and study. Journal of Listening, 4, 33–50.

A bracketed citation, [see @doe2020, p. 12], becomes "(see Doe, 2020, p. 12)", with its prefix and page.
A citation in your sentence, @muller2019 [p. 40], becomes "Müller (2019, p. 40)".
[-@doe2020] leaves the author out: "(2020)".
In a web page, each citation links to its entry in the References section.
--style chooses the style: apa (the default), mla, chicago, chicago-notes, harvard, ieee, vancouver, ama, nature, any name tw cite styles lists, or a .csl file. With a note style, such as chicago-notes, each citation becomes a footnote.

Keys are looked up in the following order, and the first library that has the key wins:

The file named with --bibliography FILE, or with a bibliography: line in the document's front matter. It can be CSL-JSON, BibTeX, BibLaTeX, or RIS, so a .bib file from another program works as it is.
references.json in the document's folder (a folder library).
Your own library, the one that tw cite add and tw cite import fill.

A key found in none of them is written as "missing reference" followed by the key, and the conversion warns you: "The citation key smith1999 is not in any library, so it reads as missing reference smith1999." Citations inside code or math are never touched. With the default gfm flavor, @name counts as a citation only when name is a key in one of the libraries, so a mention of a person or an email address stays as it is; use --flavor pandoc to have every citation formatted, as Pandoc does. --no-citations turns all of this off. See the converting guide for the other options.

Because references.json is CSL-JSON, Pandoc can also format citations from the same library: pandoc essay.md --citeproc --bibliography references.json -o essay.html. That is Pandoc's own feature.

Citations while reading and writing in textweaver

The reader uses the same libraries as tw cite: references.json in the document's folder first, then your own library.

Insert a citation: Alt+C

In edit mode, press Alt+C. textweaver reports the number of references, for example "Insert citation, 12 references. Type to filter, Enter chooses, Escape cancels." A list appears, each item reading like "Doe and Roe, 2020. On reading. Key doe2020."

Type part of an author, a year, a title word, or the key. The list keeps the references that contain every word you type and reports how many match. Backspace removes a letter.
Press Enter on the reference you want.
textweaver asks "Page or other locator, for example 12 or chapter 2; Enter for none". Type a page (12), pages (3-5 or pp. 3-5), or another division (chapter 2, section 4.1), or press Enter for none. If textweaver cannot parse what you typed, it says so and asks again.

The citation is inserted at the cursor, for example [@doe2020, p. 12], with a space before it when it follows a word, and you hear what went in: "Inserted citation of Doe and Roe, 2020, page 12." If the cursor is already inside a citation, the new reference joins it: [@doe2020, p. 12; @roe2021]. Each insertion is one undo step.

Add a reference by DOI or ISBN: Alt+B

Press Alt+B in the terminal, or Alt+Shift+D in the app (Windows Terminal keeps Alt+Shift+D for splitting its window, so the terminal key moved; see the screen reader guide), or run add reference from the command palette, and type a DOI (10.1038/nature12373, or its doi.org address) or an ISBN. You hear "Looking up" and the identifier, and you can continue reading or writing meanwhile. When the answer arrives you hear, for example, "Added reference kucsko2013. Kucsko, Maurer, and Yao, 2013. Nanometre-scale thermometry in a living cell." The reference goes into the folder's references.json when the document's folder has one, and otherwise into your own library. Lookups share the cache used by tw cite add, so an identifier looked up before works offline.

Commands from the palette

Press F2 and type part of the name:

insert bibliography: in edit mode, inserts at the cursor the formatted entries of every work the document cites, in APA style or in the style the front matter names with csl: mla. You hear the number of entries inserted and any keys that are not in a library. Place the cursor under your References heading first.
check citations: the same check as tw cite check, applied to the text you are reading or writing, for example "3 citations found. Every key is in the library."
import references: asks for a BibTeX, BibLaTeX, RIS, or CSL-JSON file and imports it into your own library, as tw cite import does.

Hear a citation in words

When a word move (the Left and Right arrows in reading) lands on a citation, or you ask for the link address there (Alt+Shift+K), textweaver speaks it in words, for example "Citation: Doe and Roe, 2020, On reading, page 12." A key that no library holds is named: "missing reference smith1999". This happens regardless of the setting below.

Citations in continuous reading: Alt+Shift+Q

By default, continuous reading skips citations: reading aloud, reading from the cursor, speaking a sentence or paragraph, and listen rendered all pass over [@doe2020, p. 12] as if it were absent. An in-text citation is part of your sentence, so for @doe2020 argues only the authors are spoken: "Doe and Roe argues".

Press Alt+Shift+Q (or run toggle citations from the palette) to have citations spoken in words, and press it again to skip them. You hear "Citations on." or "Citations off.", and the choice is saved. If textweaver is reading, it continues from the current word with the new setting.

With citations on, each is spoken from your library: "Doe and Roe, 2020, page 12" for [@doe2020, p. 12], "see Doe and Roe, 2020; Roe, 2019" for [see @doe2020; @roe2019], and "2020" for [-@doe2020]. A key that no library has is read as the key: "smith1999, page 4".

The same forms as in Write citations in Markdown are recognized.
Which @ marks count follows tw convert's rule for its default flavor: a bracketed citation counts when at least one of its keys is in a library, and an in-text @key only when every key is. An email address or a mention of a person is therefore read as written. Citations in code and math are never touched.
The highlight stays exact either way: a skipped citation is never highlighted, and while a citation is spoken in words, the whole citation is highlighted.
The libraries are the document folder's references.json, then your own library. They are reread at most once a minute, and immediately after you add or import a reference.

In settings.toml:

[reading]
citations = "off"    # or "words"

A note can name a source with a citation key, taken from the cite field in a note's front matter when you import notes from an Obsidian vault. See the vault guide.

If something goes wrong

"You may be offline; nothing was added." Check your internet connection and try again. A DOI or ISBN you looked up before still works offline, from the cache.
"did not answer within 15 seconds." The service is slow. Try again later, or wait longer with --timeout 30.
"has no record for". Check the DOI or ISBN for a typing mistake. Some books are not in Open Library; in that case export the reference from your library catalog as RIS or BibTeX and use tw cite import.
"is not a valid ISBN". A digit is mistyped; the last digit is a check digit, which is how textweaver can tell. Read the number again from the book.
Continuous reading says the brackets and the @. None of the citation's keys is in a library, so textweaver treats it as ordinary text, as tw convert does. Add the reference, or check the key's spelling.
"The citation key doe2020 is not in the reference library." Run tw cite list to find the right key. If you use a folder library, remember --folder.
"the argument '--folder ' cannot be used with '--library '". Give only one of the two.
"Could not read the BibTeX data on line 5:" and a reason. The file has a mistake on or near that line; open it and correct it, or export it again from the other program. Nothing was imported. One known case: a BibTeX file with more than one entry that has no key, such as @book{,, fails with "duplicate key". Give each entry a key, or import the data as RIS or CSL-JSON.
"Could not read the CSL-JSON data on line 2:" and a reason, for your own library. The references.json file was damaged, perhaps by a manual edit. Correct the JSON in a text editor, or move the file away and import your references again.
A wrong reference was added. Remove it with tw cite remove KEY and add the right one.
tw cite check reports keys from examples. It also counts citations inside code, such as `[@example]` or a code block. Those are not real citations and can be ignored.
A .csl file is not found. You hear "Could not read" with the file name. Check the path, and quote it if it contains spaces.