How can i use custom .csl files in my template?

Micaias_Oliveira · December 18, 2025, 11:43pm

I was making a template for an academic paper, and needed to make the citations (@book) be formatted to the right style. I found on the Parameter reference that i could use a custom .csl file that would configure the citations for me. I then wrote this on my template:

#bibliography("./bibliografia.bib", style: "./res/abnt.csl")

I have a file called abnt.csl in the folder res that on got on this github repo, but when i tried to compile, this error appeared.

[20:40:05] compiled with errors

error: failed to load CSL style (data did not match any variant of untagged enum StyleCategory)
    ┌─ res/abnt.csl:1:0
    │  
  1 │ ╭ <?xml version="1.0" encoding="utf-8"?>
  2 │ │ <style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" version="1.0">
  3 │ │   <!-- This style was edited with the Visual CSL Editor (https://editor.citationstyles.org/visualEditor/) -->
  4 │ │   <info>
    · │
725 │ │ </style>
726 │ │ 
    │ ╰^

help: error occurred in this call of function `bibliography`
    ┌─ tcc.typ:259:3
    │
259 │   #bibliography("./bibliografia.bib", style: "./res/abnt.csl")
    │    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

I am honestly not sure what is going wrong and trying to ask AI for help did not work (as with most things with Typst and AI).

I cannot test if the file works, as i did not even know what a csl file was before today. could someone help?

nleanba · December 19, 2025, 8:21am

It seems like your CSL / XML file is invalid somehow. Maybe Visual CSL Editor can help?

vmartel08 · December 19, 2025, 9:25am

I found this to be useful to validate custom CSL files: https://validator.citationstyles.org/

Y.D.X · December 19, 2025, 10:38am

Workaround

Delete the empty <category/> and <else/>.

--- a/abnt-nbr-6023-2018-nbr-10520-2023-%E2%80%93-citaca%CC%83o-numerica.csl
+++ b/abnt-nbr-6023-2018-nbr-10520-2023-%E2%80%93-citaca%CC%83o-numerica.csl
@@ -19,7 +19,6 @@
     <category citation-format="numeric"/>
     <updated>2023-09-25T04:22:28+00:00</updated>
     <rights>v0.18 (2023-09-25)</rights>
-    <category/>
   </info>
   <locale xml:lang="pt-BR">
     <terms>
@@ -582,7 +581,6 @@
                     <text macro="container-contributors"/>
                   </group>
                 </if>
-                <else/>
               </choose>
               <text macro="container-title" font-weight="normal"/>
               <text macro="advisor-or-recipient"/>
@@ -632,7 +630,6 @@
                   <if match="all" variable="title author">
                     <text term="in" text-case="capitalize-first" font-style="italic"/>
                   </if>
-                  <else/>
                 </choose>
                 <group delimiter=". ">
                   <text macro="container-contributors" text-case="uppercase"/>

According to StyleCategory in citationberg - Rust, <category> should have either citation-format or field, but that category has neither.

Also, quoting the CSL 1.0.2 spec:

As an empty cs:else element would be superfluous, cs:else must contain at least one rendering element.

Nevertheless, typst should really improve the error message for parsing CSL files.

github.com/typst/hayagriva

Improve error messages for malformed CSL files

opened 07:05PM - 06 Oct 25 UTC

YDX-2147483647

Due to the diversity of implementations, many CSL files go beyond the CSL spec, …and some even go beyond the CSL-M extension. Therefore, it would be quite helpful if we provide better error messages for malformed CSL files, for both end authors and developers. - ~~Show the place of the error in the CSL file~~ (Edit on 2026-06-10: Thanks to https://github.com/typst/citationberg/pull/23, this is no longer a problem.) - Show what data did not match any variant of the [untagged enum](https://serde.rs/enum-representations.html#untagged) - Indicate whether the CSL file is really invalid or hayagriva does not support the feature yet - (Optional) Ignore minor errors (take them as warnings) and continue parsing Relates to https://github.com/typst/citationberg/issues/22 and https://github.com/typst/citationberg/pull/23, but this issue covers more. ### Common errors According to [the survery](https://typst-doc-cn.github.io/csl-sanitizer/), **222 of 302 (74%)** CSL files in https://github.com/zotero-chinese/styles/tree/435cf756bf8bfaa193be236e27a347560ee39f54/src are considered malformed by hayagriva 799cfdc. The error messages are as the follows. - **196 (86%) × data did not match any variant of untagged enum Term** (probably caused by `space-et-al` #291) - **8 (4%) × unknown variant `institution`, expected one of `name`, `et-al`, `label`, `substitute`** (might relate to #112) - 6 × data did not match any variant of **untagged enum** Variable - 4 × data did not match any variant of **untagged enum** TextTarget - 4 × missing field `$value` - 2 × unknown variant `monograph`, expected one of `article`, `article-journal`, `article-magazine`, `article-newspaper`, `bill`, `book`, `broadcast`, `chapter`, `classic`, `collection`, `dataset`, `document`, `entry`, `entry-dictionary`, `entry-encyclopedia`, `event`, `figure`, `graphic`, `hearing`, `interview`, `legal_case`, `legislation`, `manuscript`, `map`, `motion_picture`, `musical_score`, `pamphlet`, `paper-conference`, `patent`, `performance`, `periodical`, `personal_communication`, `post`, `post-weblog`, `regulation`, `report`, `review`, `review-book`, `software`, `song`, `speech`, `standard`, `thesis`, `treaty`, `webpage` - 1 × missing field `term` - 1 × unknown variant `last`, expected `first` or `all` > The _duplicate field `layout`_ error should be the most common one at present. > It's caused by CSL-M and tracked by https://github.com/typst/citationberg/issues/5. > However, there are recent efforts improving it (e.g., #126), so I exclude this error by keeping only the last `<layout>` for `<citation>` and `<bibliography>` in CSL files. EDIT on 2025-12-22: I added a few minimal examples in https://github.com/typst-doc-cn/csl-sanitizer/tree/main/tests/normalize/ . ### Links The following discussions (in Chinese) describe the discrepancies in the CSL world. - https://github.com/zotero-chinese/styles/pull/518 - https://github.com/zotero-chinese/styles/discussions/439