Writer for typst

[jgm]

typst is a new open-source document formatting system (LaTeX alternative) with a lot of nice features. It would be nice to have a pandoc writer for it (maybe a reader too, but at this point a writer would be most useful).

[jgm]

One hurdle is that their math syntax (https://typst.app/docs/reference/math/) is not LaTeX-compatible.
So we'll need a texmath writer as well.

[tim-hilde]

Just stumbled upon typst and I am delighted to find that are planning to have a writer for it

[jgm]

I've made a start on a texmath writer as a first step. Of course, if anyone else wants to help out (especially typst experts), that would be welcome.

[jgm]

I just found out that there's already a custom pandoc reader & writer (partial support): https://github.com/lvignoli/typst-pandoc
We can learn from this.

[jgm]

The typst-writer branch now contains a working typst writer (including math support). It's currently pretty rough and needs a lot of testing and improvement.

[jgm]

A few notes:

• As far as I can see, typst does not support footnotes. I don't know if they plan to add this. We could manually create endnotes if needed. [EDIT: doing that now, until footnotes get implemented.]
• I haven't looked into automatic numbering for tables and figures, but I think this exists.
• I didn't see a way to get row/colspans in tables (but didn't look into it too much). I also didn't look into removing the lines between the cells.
• There isn't a built in definition list syntax, so I defined a function for this, allowing customization. We may want to do the same for horizontal rules and block quotes.
• I didn't see a way to get an internal link with an arbitrary text (not "Section 1"). When I figure out how to do that, I'll need to revise the handling of links with internal anchors as targets.
• I haven't delved into typst's own bibliographic support; they seem to use their own YAML format. We could in principle add conversion from the bib formats pandoc supports.
• typst has citations, but they seem to only allow suffixes, not prefixes, so it will be hard to convert pandoc citations losslessly. We should make the writer sensitive to the citations extension.

[laurmaedje]

Hey, I'm one of the developers of Typst. Very cool that you're working on this! In response to your notes:

• Yes, footnotes are missing. We will definitely add them.
• Automatic figure numbering exists, but there is also an ongoing PR to improve it: [WIP] Make ref use supplment of target element automatically typst/typst#283
• Col/rowspan is indeed also still missing
• There is definition list syntax, but its called terms
• You can create internal links, but it's currently a bit more complicated than it should be. The link function will gain support to directly link to a <label> soon.
• Typst has a custom YAML format, but BibLaTeX is supported too.
• Citations are not particularly customizable right now, unfortunately, but that will improve with time

[jgm]

@laurmaedje thanks for commenting: typst is an exciting project, and I really like a lot of the decisions that went into it. I think my main pain points right now are footnotes, tables, and citations. Glad to hear footnotes are planned.

On citations:

• Currently there is a supplement field. Standard citation systems like biblatex and CSL typically provide three things: a locator (e.g. page or chapter reference, which will be displayed in a way that is determined by the style and localized), a suffix, and a prefix. I'd recommend supporting a similar system in typst.
• Did you consider just using CSL/citeproc for citations? That would give you access to a huge collection of styles. There is already a rust library for this. Does this wheel need reinventing?
• Is there/will there be a way to specify bibliographic data inside a typst file instead of in a separate file?

On tables: Standard typographic practice is not to put lines between all cells of a table. In books, you often only have a line under the header, above the footer, and maybe below the table. (And that's pandoc's default behavior.) Maybe I'm missing something, but it seems there is no way currently to achieve this with typst. You can adjust the stroke property and get thicker or thinner lines, or no lines at all, but is there a way to get a line just below the header, for example?

Does typst have anything equivalent to LaTeX's "floats"? Currently tables seem to break between pages (so they behave like LaTeX longtable, not table which is floating).

[jgm]

On terms: This won't work as a replacement for pandoc (or LaTeX or HTML) definition lists, because they seem to add a colon in displaying the terms. This isn't always desirable; I wonder if it could be made configurable?

[jgm]

One more question @laurmaedje : I was unable to figure out how to specify alignments for table columns (e.g. first column right, second center, third left). Can you point to an example of this?

[rpitasky]

For the table strokes, I know there is a branch with a partial implementation of stroke customization, but it isn't ready to be merged quite yet.

see also typst/typst#226

[jgm]

The typst writer has been merged into the main branch.

[laurmaedje]

Does typst have anything equivalent to LaTeX's "floats"?

Floats are, similarly to footnotes, unfortunately not yet implemented.

Did you consider just using CSL/citeproc for citations? Does this wheel need reinventing?

We should definitely consider it. Typst is what it is because we have the tendency to reinvent every wheel, but sometimes it's the wrong decision.

Is there/will there be a way to specify bibliographic data inside a typst file instead of in a separate file?

No fundamental reason why there couldn't be.

Standard typographic practice is not to put lines between all cells of a table.

As mentioned before, there's a branch where I have an implementation of customizable strokes. There's lots of edge cases though, that's why I didn't get it finished in time for the beta launch.

On terms: This won't work as a replacement for pandoc because ...

You can customize it arbitrarily with a show rule:

#show terms: it => {
  it.children
    .map(child => [#child.term is #child.description])
    .join(v(6pt))
}

/ A: B
/ C: D

But if the current default style is very non-standard, I'd also be open to changing it. There's no particular reason it is that way.

I was unable to figure out how to specify alignments for table columns

You can provide a function that returns the alignment depending on the x, y cell coordinates, e.g. like this:

#table(
  columns: 3,
  align: (x, y) => (left, center, right).at(x),
  [Hello], [Hello], [Hello],
  [A], [B], [C],
)

[jgm]

But if the current default style is very non-standard, I'd also be open to changing it. There's no particular reason it is that way.

Neither LaTeX nor HTML add a colon, and in many cases this is unwanted, so I'd say it would be better for the default behavior not to add one.

But thanks for the example of customization.

Thanks also for the example of the alignment function. I saw the thing about a function from the documentation, but an example like this would have been really helpful!

[laurmaedje]

Neither LaTeX nor HTML add a colon, and in many cases this is unwanted, so I'd say it would be better for the default behavior not to add one.

I removed the colon in the default style and made the separator configurable (default is just a bit of space now).

... but an example like this would have been really helpful!

Added to the docs! (Still deploying.)

[jgm]

Great! I expect to have a new pandoc release with typst output support within the day.

[jgm]

pandoc 3.1.2 is out now with a typst writer.

[songololo]

Are there any plans for a reader? For example, would it eventually be possible to convert from typst to latex?

[jgm]

Yes, I'm starting to think about a reader. It's a bit of a complex beast, because we'll have to parse and interpret the typst language. But should be doable.

If typst ever supplies HTML output, that could be another route, since that could be passed through pandoc.

PS. Another possible route: typst/typst#461

[jgm]

I'll open a separate issue for a reader.
#8740

[mfhepp]

Does anyone have a simple, round-trip example that shows how a workflow from a typical Markdown document for Pandoc could be converted to Typst with the Pandoc writer and then rendered to a PDF document using one of the many Typst styles?

It would be really cool if the many Typst templates could be used for rendering a standard Pandoc Markdown document.

Which YAML variables would be required in the Markdown document? Etc.

[iandol]

I use Scrivener to write, converted to Pandoc markdown and rendered to PDF via Typst. Pandoc is great at building flexible Typst templates. I did this for a paper using the really nice lapreprint template https://github.com/LaPreprint/typst (you need to download the lapreprint.typ file and put it somewhere typst can find it):

My defaults file: https://github.com/iandol/dotpandoc/blob/master/defaults/lapreprint.yaml
My Pandoc template: https://github.com/iandol/dotpandoc/blob/master/templates/lapreprint.typst

The pandoc document metadata looked something like this:

---
# Typst LaPreprint Metadata
title: 'Title'
date: '`(title: "Published V3", date: datetime(year: 2023, month: 12, day: 12))`{=typst}'
short-title: PFTM
theme: '`red.darken(40%)`{=typst}'
venue: '`[bio#text(fill: red.darken(20%))[R]χiv]`{=typst}'
logo: logo.png
bibliography: Core.bib
csl: cell2022.csl
doi: '10.1101/2023.10.19.563116'
mainfont: "Alegreya Sans"
fontsize: 12pt
linestretch: 1.3
papersize: a4
lang: en
verbose: true
wrap: none
author:
  - name: Jane Doe
    equal-contributor: true
    affiliation: "2†"
  - name: Janet Doe
    orcid: "0000-0001-9985-3414"
    email: [email protected]
    affiliation: "1"
affiliations:
  - id: cebsit
    index: "1"
    name: "Institute of Neuroscience, State Key Laboratory of Neuroscience, Key Laboratory of Primate Neurobiology, Center for Excellence in Brain Science and Intelligence Technology, Chinese Academy of Sciences, Shanghai 200031, China"
  - id: inserm
    index: "2"
    name: "Sorbonne Université, Inserm, CNRS, ICM, Paris, France"
  - id: eq
    index: "†"
    name: Equal contribution
keywords: [color perception, pupillometry, no-report paradigm, frequency-tagging, isoluminance]
margin-correspondence:
  - "Jane: [[email protected]](mailto:[email protected])"
  - "Janet: [[email protected]](mailto:[email protected])"
margin-keypoints:
  - "Lorum ipsum blah blah blah."
  - "Lorum ipsum blah blah blah."
  - "Lorum ipsum blah blah blah."
margin-funding:
  - "This work was supported by the following grants: National Science and Technology Innovation 2030 Major Program XXX (to Janet), Shanghai Municipal Science and Technology Major Project 2018SHZDZX05 (to Jane), National Natural Science Foundation of China grants 32070992 and 32150410370 (to Jane) and 32100805 (to Jane)."
margin-code:
  - "Code to run can be found online."
---

I made a filter that fixes a couple of issues i had with syntax (e.g. typst uses <fig-label> to label items which is raw html, the filter converts them to raw typst, and uses @fig-label for crossrefs which is also pandocs @cite, so the filter checks the label and if it is @fig- or @tbl- etc. converts it from a citation to raw typst: https://github.com/iandol/dotpandoc/blob/master/filters/typstFix.lua

I also have custom typst templates for standard docs, you can look through my dotpandoc templates folder: https://github.com/iandol/dotpandoc/tree/master/templates -- I have to modify things as I use academic metadata