Converting Zensical md files to one pdf using Pandoc and Typst

zensical_pdf.md

Convert Zensical md files to one pdf using Pandoc and Typst

The flow is:

• convert markdown .md files to a typst .typ file , using pandoc
• using the typst compiler convert the .typ file to pdf
• alternatively, using the typst web app edit the .typ file, preview changes in real time and export to pdf.

I wanted to convert my Zensical documentation to a pdf with an academic flavour. While there are alternative ways of doing this (such as using a former Mkdocs plugin) the process I chose gives me full control of the resulting pdf. Typst uses its own markdown but is quite easy to learn. Typst also has many templates, contributed by the community.

Convert .md files to one .typ file using pandoc

1. Move all md files into a folder - My_md_folder.

2. For pandoc, I used docker. There are a few flavours of pandoc in Docker Hub. I used the pandoc/typst image. This is set up to use typst.

   docker pull pandoc/typst:latest-ubuntu
   
   # Start a container, binding the internal /data directory to your "My_md_folder"
   docker run -it --volume "<path to My_md_folder>:/data" --user `id -u`:`id -g` pandoc/typst:latest-ubuntu

3. I used Docker Desktop to enter the container. Go to Exec in the container then:

   # Start a bash shell
   bash
   
   # Convert md files to a typst file
   pandoc one.md two.md three.md -t typst -o mytypst.typ

   The output file, mytypst.typ, will be in your My_md_folder.

Convert .typ file to .pdf

1. Install the typst compiler (I was on macos so did brew install typst).

2. Go to Typst Universe and decide on a template. Create a typst project with the template.

   typst init @preview/arkheion:0.1.2

3. Retrieve the template. In VSCode open the project. The example typ file (in this case 'main.typ', will have a statement at its top to import the template. We need to copy this template. If in VSCode, right-click it and go to its definition in order to copy it. Alternatively, the template can be found on the repository for templates on Github.

4. Copy the template to the top of your own .typ file - mytypst.typ.

5. Follow this with a copy of the code in main.typ which applies the template. In my case, using the arkheion template, the code was:

   #show: arkheion.with(
     title: "Typst Template for arXiv",
     authors: (
       (name: "Author 1", email: "user@domain.com", affiliation: "Company", orcid: "0000-0000-0000-0000"),
       (name: "Author 2", email: "user@domain.com", affiliation: "Company"),
     ),
     // Insert your abstract after the colon, wrapped in brackets.
     // Example: `abstract: [This is my abstract...]`
     abstract: lorem(55),
     keywords: ("First keyword", "Second keyword", "etc."),
     date: "May 16, 2023",
   )
   #set cite(style: "chicago-author-date")
   #show link: underline

   The mytypst.typ file should now contain the imported template, followed by the code above, followed by your own content.

6. Compile this new mytypst.typ file into a pdf:

   typst mytypst.typ test.pdf

   In my case I found I needed to also copy across a .svg file before it would compile without errors.

Using the typst web app

If you want to fine tune the template, you can do that in VSCode but you might want to use the typst web app. You can preview changes in realtime. It is free.

Using pandoc/typst for the whole process

It is possible to convert md files to pdf without installing the typst compiler. I wanted ultimate control over the resulting pdf and so chose to work directly with typst. The easier process is, in the container:

pandoc one.md two.md three.md --pdf-engine=typst -o mypdf.pdf