Alexandria -- multiple bibliographies in the same document!

SillyFreak · February 6, 2025, 5:39pm

~~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",
)

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.

SillyFreak · February 13, 2025, 12:59pm

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:

TheZoq2 · February 21, 2025, 12:11pm

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

SillyFreak · February 21, 2025, 1:53pm

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.

Nihilol · February 27, 2025, 11:58am

Could you possible make a snippet of this code? I’m trying to do the exact same thing, but I’m having some trouble figuring it out :)

SillyFreak · February 27, 2025, 12:03pm

you can take inspiration from the manual. since it contains multiple examples, that’s basically the same as having multiple chapters:

Nihilol · February 27, 2025, 1:16pm

Thank you! I got it to work with what I wanted it to do, with a few work-arounds :)

SillyFreak · February 27, 2025, 2:11pm

If you don’t mind, I’d be interested in the workarounds so I know if there’s anything specific that needs improving

Nihilol · March 1, 2025, 12:01pm

Of course!

The main thing I wanted was for the bibliography to not show up as a separate chapter, as it belongs to the previous chapter, which I fixed by naming all of the various chapter bibliographies “Bibliography” and then set the following show rule:

show heading: it => {
    let levels = counter(heading).at(it.location())
    if it.level == 1 {
        if it.body == [Bibliography] {
            set align(center)
            text(it.body + " For Chapter " + str(counter(heading).get().first() - 1), fill: header_colour) 
            counter(heading).update(counter(heading).get().first() - 1)
        }
    }
}

This essentially just means that the smaller, non-numbered header for the bibliography will read: “Bibliography for Chapter [insert chapter number]”

Hope this is what you were looking for.

SillyFreak · March 1, 2025, 6:53pm

I see! Since your code seems to not format the non-bibliography headings, I tried to fix it up a bit and added the surrounding boilerplate to make it directly reproducible (if you provide a bibliography file):

for reference: original in a complete example

#import "@preview/alexandria:0.1.1": *

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

#set heading(numbering: "1.")

#show heading: it => {
  if it.level != 1 or it.body != [Bibliography] { return it }

  let levels = counter(heading).at(it.location())
  set align(center)
  text(it.body + " For Chapter " + str(counter(heading).get().first() - 1)) 
  counter(heading).update(counter(heading).get().first() - 1)
}

= A

#bibliographyx("ref.bib", title: [Bibliography])

= B

#bibliographyx("ref.bib", title: [Bibliography])

If you find that my suggestions below don’t do what you want, check first if I got this right; maybe I misunderstood your intent.

A few things that you should fix about this are regarding the following:

your bib headings aren’t blocks
you are using get() → update() for the counter; starting with the third chapter, this stops working with the dreaded “Layout did not converge within 5 attempts” – see here: Why is State Final not "final"? - #2 by SillyFreak

so you should at least adapt this to the following:

fixed block and convergence

#import "@preview/alexandria:0.1.1": *

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

#set heading(numbering: "1.")

#show heading: it => {
  if it.level != 1 or it.body != [Bibliography] { return it }

  set align(center)
  block[
    #it.body for Chapter #(counter(heading).get().first() - 1)
  ]
  counter(heading).update(value => value - 1)
}

= A

#bibliographyx("ref.bib", title: [Bibliography])

= B

#bibliographyx("ref.bib", title: [Bibliography])

The workaround that you used is for the problem that you can’t write show bibliography: set heading(...) with Alexandria. Personally, for now I would solve that with a function. The advantage is that you don’t need to fiddle with the heading counter, since this way you can disable the heading numbering. It will also play more nicely with an outline, since the text is not only changed through the show rule but for the heading as a whole. And you can also set heading(outlined: none) if you want. You can see the difference by adding #outline() to the examples:

different workaround with a function

#import "@preview/alexandria:0.1.1": alexandria, bibliographyx as _bibliographyx

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

#set heading(numbering: "1.")

#let bibliographyx(..args) = {
  show heading: set align(center)
  set heading(numbering: none)
  _bibliographyx(
    title: [Bibliography for Chapter #context (counter(heading).get().first())],
    ..args,
  )
}

= A

#bibliographyx("ref.bib")

= B

#bibliographyx("ref.bib")

Nihilol · March 16, 2025, 1:03pm

Sorry for the long response time.

I’ve managed to get it to work with a function like you suggested, so I don’t manually increase the counters.
Thanks for the help!