Typst writer: two common LaTeX constructs produce output that does not compile (`\ref` to a section, `thebibliography`)

[Supersynergy]

Summary

Converting ordinary LaTeX to Typst produces .typ files that fail typst compile with a hard error
for two very common constructs. Unlike the HTML/DOCX writers, Typst has a compile step, so these
degrade from "renders slightly differently" to "produces no document at all".

Both have small, well-scoped fixes. Tested with pandoc 3.10.1 and typst 0.15.1.

---

Case A: \ref to a section

\documentclass{article}\begin{document}
\section{Intro}\label{sec:i}
See \ref{sec:i}.
\end{document}

$ pandoc -s -f latex -t typst a.tex -o a.typ
$ typst compile a.typ
error: cannot reference heading without numbering
    ┌─ a.typ:150:4
    │
150 │ See @sec:i.
    │     ^^^^^^
    │
    = hint: you can enable heading numbering with `#set heading(numbering: "1.")`

The writer emits @sec:i, but nothing sets heading numbering. article numbers sections by
default in LaTeX, so this affects essentially every structured LaTeX document that uses \ref.

The default Typst template already supports this. It never receives the value:

$ pandoc --print-default-template=typst | grep -n section-numbering
104:$if(section-numbering)$
105:  sectionnumbering: "$section-numbering$",

Confirmed workaround:

$ pandoc -s -f latex -t typst -M section-numbering="1.1" a.tex -o a.typ && typst compile a.typ
# succeeds

Suggested fix: have the LaTeX reader set section-numbering when the document class numbers
sections and \ref targets exist (mirroring the LaTeX default), or have the Typst writer fall back
to a plain #link(<label>)[…] when it cannot guarantee the target is numbered.

---

Case B: thebibliography, where the root cause is in the LaTeX reader

\documentclass{article}\begin{document}
Text \cite{k}.
\begin{thebibliography}{9}\bibitem{k} Knuth.\end{thebibliography}
\end{document}

$ pandoc -s -f latex -t typst b.tex -o b.typ
$ typst compile b.typ
error: label `<k>` does not exist in the document
    ┌─ b.typ:148:5
    │
148 │ Text @k.
    │      ^^

The reader drops the \bibitem key entirely. The resulting Span has an empty identifier:

$ pandoc -f latex -t native b.tex | tail -4
, Div
    ( "" , [ "thebibliography" ] , [] )
    [ Para
        [ Span ( "" , [] , [] ) [ Str "9" ] , Space , Str "Knuth." ]

The \cite{k} still becomes a Cite with citationId = "k", which the Typst writer renders as
@k. Since the key never reached the bibliography entry, the label does not exist.

This is also visible (less harmfully) in the HTML writer, which emits an empty citation:

$ pandoc -f latex -t html b.tex
<p>Text <span class="citation" data-cites="k"></span>.</p>
<div class="thebibliography">
<p><span>9</span> Knuth.</p>
</div>

--citeproc is not a workaround. It compiles, but silently drops the citation:

$ pandoc -s -f latex -t typst --citeproc b.tex -o b2.typ
[WARNING] Citeproc: citation k not found

The BibTeX path works correctly, which isolates the problem to thebibliography:

$ printf '\\documentclass{article}\\begin{document}\nText \\cite{k}.\n\\bibliography{r}\n\\end{document}\n' > c.tex
$ pandoc -s -f latex -t typst c.tex -o c.typ && typst compile c.typ   # succeeds
$ grep bibliography c.typ
#bibliography(("r.bib"))

Minimal fix: preserve the \bibitem key as the identifier on the emitted Span
(or on a wrapping Div), so writers can attach a label. That alone makes the Typst output compile
and simultaneously fixes the empty data-cites span in the HTML writer.

Fuller fix: have the Typst writer emit #bibliography entries, or attach <key>
labels to each bibliography item.

---

Reproduction script

#!/usr/bin/env bash
set -uo pipefail
run() {
  pandoc -s -f latex -t typst "$1.tex" -o "$1.typ" || return 1
  if typst compile "$1.typ" "$1.pdf" >/dev/null 2>&1
    then printf '%-2s compiles=YES\n' "$1"
    else printf '%-2s compiles=NO\n'  "$1"; typst compile "$1.typ" "$1.pdf" 2>&1 | head -3
  fi
}
run a   # NO  — \ref to section
run b   # NO  — thebibliography
run c   # YES — \bibliography{r.bib}
run d   # YES — title/author/math

Observed on pandoc 3.10.1 / typst 0.15.1 / macOS 15 arm64.

---

Why this matters beyond the two cases

The Typst writer handles the rest well. Headings, labels, math, booktabs tables
(table.hline), figures, \title/\author, and \bibliography{x.bib} all convert cleanly.
These two gaps are what make "convert an existing LaTeX paper to Typst" fail in practice, since \ref and an inline
thebibliography appear in a large share of real documents, including many self-contained
conference and journal submissions where thebibliography is required rather than optional.

I am happy to prepare a PR for the reader-side \bibitem identifier fix if the approach looks right.

[jgm]

Case A: LaTeX does not automatically turn on section numbering if \ref is used. If section numbering is turned off in the preamble (as it is by default in pandoc), it stays turned off and you just get an empty hyperlink. So, typst produces an error instead of an empty hyperlink. The solution is to specify section numbering using --number-sections. Pandoc could enable that magically if the document includes a reference, but I'm not sure that's the right approach -- it violates a pandoc expectation that you'll only get section numbers if you asked for them.

Case B: Interesting. Why would someone write a LaTeX document this way, instead of using bibtex/biblatex?

[Supersynergy]

Thanks, that clears up Case A. You are right that pandoc should not silently turn on
numbering, and --number-sections is the correct answer. I withdraw the suggested fix.

What is left of Case A is narrower. With every other writer an unresolvable \ref degrades to
an empty hyperlink, while the Typst writer emits @sec:i, which is a hard compile error. If it
emitted #link(<sec:i>)[] when numbering is not enabled, the behaviour would match the HTML
writer and the document would still build. Happy to drop this if you would rather keep the
writer simple and treat it as a documentation matter.

Case B: nobody writes it, BibTeX writes it

thebibliography is not a hand-written style. It is the output format of BibTeX. The .bbl
file that bibtex produces is a thebibliography environment:

$ cat p.tex
\documentclass{article}
\begin{document}
Text \cite{k}.
\bibliographystyle{plain}
\bibliography{r}
\end{document}

$ tectonic -X compile p.tex --keep-intermediates
$ cat p.bbl
\begin{thebibliography}{1}

\bibitem{k}
Donald~E. Knuth.
\newblock {\em The TeXbook}.
\newblock Addison-Wesley, 1984.

\end{thebibliography}

So the construct appears whenever a .bbl ends up inside the document, and that is the normal
shape of a submission rather than an edge case. arXiv's TeX submission page requires it: "you
must pre-compile the bibliography, upload the .bbl file", and arXiv uses the .bbl if one is
present. Many journal and conference workflows do the same, because the submitted source has
to build without the author's .bib.

That shape fails today:

$ cat arxiv.tex
\documentclass{article}
\begin{document}
Text \cite{k}.
\input{p.bbl}
\end{document}

$ tectonic -X compile arxiv.tex          # builds fine
$ pandoc -s -f latex -t typst arxiv.tex -o arxiv.typ
$ typst compile arxiv.typ
error: label `<k>` does not exist in the document
    ┌─ arxiv.typ:148:5
    │
148 │ Text @k.
    │      ^^

For scale, GitHub code search reports about 27,400 .tex files containing
\begin{thebibliography} and about 41,700 containing \bibitem.

The reader-side part looks independent of the Typst writer: \bibitem{k} currently produces
Span ("" , [] , []), so the key is dropped before any writer sees it. Keeping it as the
identifier would also fix the empty data-cites span that the HTML writer emits for the same
input. I am happy to prepare that patch if the approach seems right to you.

[jgm]

If it emitted #link(<sec:i>)[] when numbering is not enabled, the behaviour would match the HTML
writer and the document would still build.

The problem is that the parser only takes reader options as a parameter, and you'd need to look in writer options to see if numbering is enabled. So, I think I'll pass on the suggestion, though it's entirely reasonable.

Case B: okay, point taken. It would be good to do something better here, I agree.

[jgm]

Wrapping the bibitems in a Div with an id seems a good first step. I'm curious what the fuller solution that you alluded to (generating a typst #bibliography) would look like. IIRC, typst #bibliography takes a file with a bibliographic database as argument, not an already formatted bibliography like the kind supplied here.

[Supersynergy]

You are right, and that kills the wording I used. #bibliography takes a Hayagriva or BibTeX
database, so a pre-formatted .bbl cannot go through it. Worse, the direction is not
recoverable: by the time LaTeX has run BibTeX, the fields are gone and only rendered text is
left, so there is no honest way to reconstruct a database from \bibitem bodies.

So the fuller solution is not #bibliography at all. It is "make each entry a referenceable
element", which is exactly what your Div-with-an-id step enables.

One wrinkle is worth knowing before designing it. A label on a plain block is not
referenceable in Typst.

$ cat v1.typ
Text @k.

#block[[1] Donald E. Knuth. The TeXbook. Addison-Wesley, 1984.] <k>

$ typst compile v1.typ
error: cannot reference block
  ┌─ v1.typ:1:5
  │
1 │ Text @k.

figure with a custom kind is referenceable, and it brings its own counter, which happens to
match how thebibliography numbers entries. Verified on typst 0.15.1:

// template side, would live in default.typst
#let bibnum(loc) = counter(figure.where(kind: "bibitem")).at(loc).first()

#show figure.where(kind: "bibitem"): it => {
  set align(left)
  block(width: 100%, above: 0.65em, grid(
    columns: (1.8em, 1fr), gutter: 0.3em,
    context [\[#bibnum(it.location())\]],
    it.body,
  ))
}

#show ref: it => {
  let e = it.element
  if e != none and e.func() == figure and e.kind == "bibitem" {
    link(it.target)[#context [\[#bibnum(e.location())\]]]
  } else {
    it
  }
}

// writer side, one of these per \bibitem
Text @k and @b.

#figure(kind: "bibitem", supplement: none, numbering: "1", caption: none)[
  Donald E. Knuth. #emph[The TeXbook]. Addison-Wesley, 1984.
] <k>

#figure(kind: "bibitem", supplement: none, numbering: "1", caption: none)[
  Leslie Lamport. #emph[LaTeX: A Document Preparation System]. 1994.
] <b>

That renders as Text [1] and [2]. with a numbered, left-aligned, hanging-indent list, which
matches plain thebibliography output.

The split matters for where the work goes. Everything above the comment is template material,
about a dozen lines in default.typst, and it is the same for every document. The writer only
has to emit the #figure(...)[...] <key> form, which is a fairly direct mapping from a
Div ("key", ["thebibliography-item"], []).

Two caveats I have not solved:

Numbering only agrees with LaTeX when entry order equals label order, which is the normal case
for a .bbl but not guaranteed. LaTeX takes the number from the entry position too, so I think
this matches, but I have not tested a document where \bibitem labels are reordered by hand.

\bibitem[Knuth 1984]{k} with an explicit optional label would need the given text instead of
the counter, so the writer would have to pass it through and the show rule would prefer it over
bibnum.

If the Div step lands, I am happy to try the writer side and this template snippet as a follow-up
and report what breaks on real .bbl files.

[jgm]

I'm not sure -- this feels quite fragile and it is adding a lot of complexity. Wouldn't it normally be the case that the original .tex file with cite commands and the original .bib file are also available, so one could just use those together with citeproc to get excellent and much more correct results in typst?

[Supersynergy]

You are right, and I checked how right. I pulled the source packages of 25 recent cs.CL
submissions from arxiv.org/e-print and looked at what they contain:

	count
contains a .bib	20 of 25
no .bib at all	5 of 25
of those: .bbl only	3
of those: thebibliography written inline in the .tex	2

So in four out of five cases the database is right there and --citeproc is the correct answer.
That path already works well today:

$ pandoc -s -f latex -t typst --citeproc --bibliography=r.bib p.tex -o cp.typ
$ typst compile cp.typ        # builds
$ grep Knuth cp.typ
Text \(Knuth 1984).

I am dropping the show-rule proposal. It was a workaround for a case that citeproc covers
better, and you are right that the counter plus two show rules is a lot of machinery to carry in
the default template for a minority of documents.

One thing from my earlier suggestion does not survive contact with the compiler, though, and it
affects the Div step you were happy with. A label on a plain block is not referenceable in
Typst, and a Div with an identifier is exactly what the writer turns into a block:

$ pandoc -f markdown -t typst <<'EOF'
Text [@k].

::: {#k}
Donald E. Knuth. *The TeXbook*. Addison-Wesley, 1984.
:::
EOF
Text @k.

#block[
Donald E. Knuth. #emph[The TeXbook]. Addison-Wesley, 1984.

] <k>

$ typst compile that.typ
error: cannot reference block

So carrying the \bibitem key through to a Div is still worth doing, but on its own it changes
the error from label <k> does not exist to cannot reference block rather than producing a
document.

If you want the remaining 20 percent to build rather than fail, the smaller lever is on the
citation side: when there is no bibliography for @k to resolve against, emit
#link(<k>)[k] instead of @k. That compiles against a labelled block, needs no template
support, and keeps @k for the citeproc path where it is correct.

Happy to leave the 20 percent failing if you would rather keep the writer simple and document
--citeproc as the supported route. Either way the measurement above is yours to use.