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.

18 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

3 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.

5

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 :)

6

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

7

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

8

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

9

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.

10

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")
11

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!

12

Actually, now that I look at it a bit more, your function doesn’t seem to provide the functionality it wants to.

If you make the outline, with the #contect (counter(heading).get().first()), then it gives the header counter of 0 in all of the outline. Do you know how to work around that?

Thanks!

13

This package is great! Together with the workarounds you mentioned, I was able to implement multiple bibliographies into my PhD thesis, thanks!

Collapsing of citations would be a nice addition though. I am very new to Typst and wanted to try and write a wrapper function for this. This is when encountered a problem with the #cite function. When using #cite(<label>, form: none), with the goal of adding the reference to de bibliography without having a citation, I encountered an error. Am I doing something wrong here?

14

I’ll have to investigate, but probably not. form: none works for regular citations (without Alexandria)? Then it’s a but and should be reported.

Is your approach with the none form basically to get (as an example) 1 and 2 instead of [1] and [2] so you can combine them manually to [1, 2]? That should work (if I fix that bug). Proper support will require me to do it in Alexandria, because collapsed citations require me to pass the citations differently to Hayagriva, which a user of Alexandria can not do themselves.

Feel free to also open a feature request for citation collapsing. If you have a timeline for your thesis (and it’s not due in a week :stuck_out_tongue:) I’ll be sure to implement it in time! :slight_smile:

15

This is indeed the approach I wanted to try. form: none does seem to be working fine without Alexandria, so it is probably a bug. I am not very experienced with code development, but I will try to report in on Github.

I still have a few months to finish it, so I’ll also try to put in the feature request. Thank you for the great support!

1 Like
16

I noticed that you merged a PR to get citation collapsing working last week, any chance you could do a release to typst universe so I can use it in my thesis more easily?

Otherwise my advisor will not stop complaining about non-collapsed citations in my thesis