workspace-course-topics

Assignment: Export Ballpark to PDF or MyST Markdown

Prerequisites:

MyST Assembly and PR — your ballpark has myst.yml, four notebooks, and a working myst build
Your ballpark fork is synced with upstream and your local clone is pulled (so you have the updated .gitignore)

Throughout this document, {BALLPARK} stands for your paper’s folder name (e.g. Benhabib_et_al_2019, OptimumDebt). Always replace it with your actual folder name.

Before you start: Download the paper PDF and convert to LaTeX

Create source/ inside your paper folder: models/We-Would-Like-In-Econ-ARK/{BALLPARK}/source/
Download the paper PDF from its original publication source (e.g. via PaperPile and the JHU library) and save it into source/.
Use MathPix Snip (or equivalent) to convert the PDF to LaTeX. Save the LaTeX output in source/ as well.

The .gitignore includes source/**, so nothing in source/ (the PDF or the LaTeX) will be committed or pushed. Both stay local to avoid sharing copyrighted content.

Objective

Use one of the tools introduced in class to convert your ballpark paper into either a PDF or MyST Markdown (.md) document — or both. This gives you a portable, shareable version of your assembled ballpark entry.

Where to work

Work in your ballpark paper folder:

cd ~/github/<your-username>/ballpark/models/We-Would-Like-In-Econ-ARK/{BALLPARK}/

Tools from class

Tool	Purpose	Output
MyST CLI (`myst build`)	Build the assembled document	HTML site; can add PDF export
Jupytext	Convert notebooks to MyST Markdown	`.md` files from `.ipynb`

Option A: Export to PDF

A1. Simple path — Print from built HTML

Run myst build in your paper folder.
Open the built HTML in a browser (e.g. _build/site/public/index-*.md rendered, or serve the site).
Use the browser’s Print → Save as PDF to create a PDF.

No LaTeX required.

A2. MyST PDF export (requires LaTeX or Typst)

Add an export to your myst.yml:

# Add under project: in myst.yml
exports:
  - format: pdf
    template: arxiv_two_column
    output: exports/{BALLPARK}.pdf

Then run:

myst build --pdf

Requirements: LaTeX (e.g. MacTeX, TeX Live) or Typst must be installed. See MyST: Create a PDF.

Templates: List available templates with myst templates list --pdf. Use plain_latex_book or arxiv_two_column for a simple start.

Option B: Export to MyST Markdown (.md)

Use Jupytext to convert each notebook to MyST Markdown:

# Convert all four notebooks to .md
jupytext --to myst {BALLPARK}_intro.ipynb
jupytext --to myst {BALLPARK}_prior-literature.ipynb
jupytext --to myst {BALLPARK}_summary.ipynb
jupytext --to myst {BALLPARK}_subsequent-literature.ipynb

This creates .md files alongside each notebook. The .md files are plain text, version-control friendly, and can be edited directly or round-tripped back to .ipynb with Jupytext.

Deliverable

Submit at least one of:

A PDF of your assembled ballpark (from Option A1 or A2), or
MyST Markdown (.md) versions of your notebooks (from Option B), or
Both

Include a brief note on which tool(s) you used and any issues you ran into.

Verification

PDF: Opens correctly and shows all four sections (intro, prior lit, summary, subsequent lit)
MMD: Each .md file renders correctly and preserves citations and structure

Troubleshooting

myst build --pdf fails with “LaTeX not found”:

Install LaTeX (MacTeX on macOS, TeX Live on Linux) or Typst
Or use Option A1 (print from HTML) instead

Jupytext produces unexpected output:

Ensure you’re in the paper folder and using the correct notebook names
Check jupytext --version — you need jupytext installed (e.g. via pip install jupytext or bash scripts/setup_env.sh in ballpark)

Citations missing in PDF:

Verify self.bib, references.bib, and subsequent-literature.bib are listed in myst.yml under project: bibliography:

If You Get Stuck

Ask Cursor AI. If the “auto” model is inadequate, try Claude Opus 4.6 or ChatGPT 5.3.