Alexandria -- multiple bibliographies in the same document!

Showcase
,
1

This package is not merged yet, but I’m fairly excited about it so I wanted to share it right away: Alexandria (Github) allows you to create any number of bibliographies in the same document. It achieves that by using Hayagriva (Typst’s citation engine) as a WASM plugin, thus supporting all citation styles* that Typst supports natively!

Demo

Example source code 
#import "@preview/alexandria:0.1.0": *

#show: alexandria(prefix: "x-", read: path => read(path))
#show: alexandria(prefix: "y-", read: path => read(path))

= Section 1

For further information, see #cite(<x-netwok>, form: "prose").

#bibliographyx(
  "bibliography.bib",
  prefix: "x-",
  title: "Bibliography",
)

= Section 2

We will now look at pirate organizations. @y-arrgh

#bibliographyx(
  "bibliography.bib",
  prefix: "y-",
  title: "Bibliography",
)

example
example2067×767 109 KB

You give Alexandria a prefix and a function so that it can read your bibliography files, and then you can cite sources like @x-netwok. All references using that prefix will go through Alexandria, and will be collected by bibliographyx() (so don’t use regular labels with that prefix!).

If you use multiple Alexandria bibliographies, you will also need to specify the prefix for each bibliography. Each bibliography needs a separate prefix, so that citations can be matched with the bibliographies they belong to.

Limitations

*all citation styles? Well, in theory. I am aware of a few things that are not supported yet:

  • Citation collapsing: multiple adjacent citations are processed separately. I don’t think I can fix that, but I can provide a function for wrapping multiple citations that would then be treated as a group.
  • Footnote citations: I simply haven’t looked into them yet.
  • Show and set rules: this is the hardest; Alexandria converts citations into links, so the “wrong” rules will apply to Alexandria citations. There’s not really a way around this. Likewise, using show bibliography: set heading(...) – or any show bibliography rule, really – won’t have an effect.
  • Using bibliographyx(title: auto) doesn’t work. At least for now, you’ll need to localize your bibliography title yourself.

One more thing to note is that all bibliographies generated this way are completely independent. As you can see in the example, there are two [1] citations referring to different sources. If the “scopes” of your bibliographies overlap, this will be annoying!

If you note anything else, please let me know here or open an issue on Github.

Future plans

Apart from footnotes and collapsed citations, I want to make Alexandria more general. The reason replicating native bibliographies is not super trivial is that you can’t inspect a bibliography element: what citations does your document have? What references does the bibliography contain?

Not making this information available to Alexandria’s users makes it only half as useful as it could be. With this information, you could add “one” Alexandria Bibliography to your document, but then split the references into two pieces and render them separately, resulting in unique citation keys and fixing the issue of overlapping scopes.

A few foundations for this are there, but the necessary documentation and convenient APIs are still missing.

14 Likes
2

It’s been a week, and I have basically added these future plans, plus some more (though the limitations I listed remain). Version 0.1.1 is out, and it

  • adds functions load-bibliography that stores bib data for later retrieval, get-bibliography that retrieves the data, and render-bibliography that renders the bib data. Together they do the job of bibliographyx, but now you can also use them separately

  • also loads structured data from the bibliography, e.g. you can call

    get-bibliography("x-").references
  .filter(x => x.details.type == "book")
  .map(x => x.details.title)

    to get the titles of all books in your bibliography (only the ones appearing in your document, i.e. the ones that were cited unless your bibliography uses full: true).

    The main use case for this is loading a bibliography once, then rendering parts of it separately – see the example below.

  • adds support for custom CSL styles loaded from files. just specify bibliographyx(style: "my-custom-style.csl") and it will be used instead of one of the built-in styles.

  • fix a deprecation warning that would appear in 0.13

The new APIs are well-documented in the manual, here’s the page demonstrating a “split” bibliography:

image

2 Likes
3

Wow, that’s nice! I need this for my thesis so i’m very glad I won’t have to figure it out on my own :)

Actually, after trying it out, I’m not sure it does what I want. What I want is a bibliography per chapter, but a lot of references will occur in more than one bibliography since I cite the same works in multiple chapters. Is that something that could be supported?

Edit: One more update: I got this working by using different prefixes for each chapter

4

Thanks :)

Yes, if your references are per chapter, each chapter needs its own prefix. I can imagine some ways to lift this restriction, but they’d probably be confined to very specific kinds of requirements (like exactly one bibliography by chapter, no overlap or others). So right now you have to use the prefixes to manually associate each citation with a specific bibliography, and in return have the ability to cite from anywhere in your document.