workspace-course-topics

Assignment: MyST Assembly and PR

Due: Before next class

Prerequisites:

Create Intro Notebook — {BALLPARK}_intro.ipynb exists
Create Prior-Literature Notebook — {BALLPARK}_prior-literature.ipynb and self.bib exist
Create Subsequent-Literature Notebook — {BALLPARK}_subsequent-literature.ipynb exists
self.bib, references.bib, and subsequent-literature.bib in the paper folder

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

Objective

Improve the summary notebook (fix typos, heading hierarchy, cross-references, images), add MyST citations, create a myst.yml configuration that weaves all four notebooks together via a table of contents, verify the build, and submit your pull request.

Example: See the completed Benhabib_et_al_2019 ballpark entry for a model of the finished product.

Where to work

Work in your fork, on the same branch you used to open your original ballpark PR:

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

Already have a fork and PR branch? You should — see the Class 05 assignment, Step 0. If not, see the setup instructions in Create Intro Notebook, Part A.

Steps

Step 1. Fix typos and grammar in the summary notebook

Open {BALLPARK}_summary.ipynb and read through the existing text. Fix any clear spelling or grammatical errors (e.g. “Weath” -> “Wealth”, “retturn” -> “return”). Do not rewrite the original author’s prose — just fix clear errors.

Step 2. Fix heading hierarchy

The summary notebook must have a single # (h1) heading as its document title — MyST uses this as the table-of-contents entry. All subsequent sections should be ##, subsections ###, etc. If the existing headings skip levels or start at ##, fix the hierarchy.

Step 3. Modernize images

If the notebook contains raw HTML <img> tags, replace them with Markdown image syntax with descriptive alt text:

![Comparison of wealth distribution: model vs. data](fig1.png)

Do not use generic alt text like “Alt text” or “Optional title”.

Step 4. Add MyST citations to the summary notebook

In {BALLPARK}_summary.ipynb:

Where the notebook mentions specific papers by name, add MyST citation syntax: {cite:t}keyor `{cite:p}`key
Citation keys come from references.bib, self.bib, or subsequent-literature.bib
Do not duplicate the prior-literature or subsequent-literature content here; that lives in the dedicated notebooks

Step 5. Add cross-references as Markdown links

At appropriate points in the summary notebook, add brief connecting remarks that link to the companion notebooks. Cross-references must be clickable Markdown links, not just bold text:

For a detailed discussion of the foundational literature, see the
[Prior Literature]({BALLPARK}_prior-literature.ipynb) notebook.

For how later work addresses these issues, see the
[Subsequent Literature]({BALLPARK}_subsequent-literature.ipynb) notebook.

Keep cross-references light — one or two sentences each.

Step 6. Create `myst.yml`

Create a myst.yml file in the paper folder that defines the table of contents and bibliography:

# myst.yml in models/We-Would-Like-In-Econ-ARK/{BALLPARK}/
version: 1

project:
  title: "[Paper Title] — Ballpark Entry"
  bibliography:
    - self.bib
    - references.bib
    - subsequent-literature.bib
  toc:
    - file: {BALLPARK}_intro.ipynb
    - file: {BALLPARK}_prior-literature.ipynb
    - file: {BALLPARK}_summary.ipynb
    - file: {BALLPARK}_subsequent-literature.ipynb

site:
  title: "[Paper Title] — Ballpark Entry"

Replace {BALLPARK} with your actual folder name and [Paper Title] with the paper title. Note self.bib is listed first in the bibliography.

Step 7. Verify the build

myst build

What to check:

Build completes without errors
Citations resolve (no “undefined citation” warnings)
HTML output shows a rendered bibliography

If myst is not recognized, re-run bash scripts/setup_env.sh or see the MyST CLI reference.

Step 8. Ask Cursor to review your changes

Before pushing, ask Cursor to check your work:

“I’m about to create a pull request to econ-ark/ballpark. Can you review my changes and tell me if anything looks wrong?”

You can also inspect what you’re about to commit:

git diff
git status

Step 9. Commit and push

git add .
git commit -m "Add four-notebook MyST assembly with citations and TOC"
git push origin <your-PR-branch>

Replace origin with your fork’s remote name and <your-PR-branch> with your branch name. If you don’t remember your branch name, run git branch --show-current.

Step 10. Create a pull request

Go to https://github.com/econ-ark/ballpark
You should see a banner: “Compare & pull request” for your recently pushed branch
Click it
Fill in the PR:
- Title: “Add MyST assembly for [Paper Name] — [Your Name]”
- Description: ``` Four-notebook MyST assembly for the [Paper Name] ballpark entry:
  - {BALLPARK}_intro.ipynb — paper metadata, attribution (SST)
  - {BALLPARK}_prior-literature.ipynb — prior literature with MyST citations
  - {BALLPARK}_summary.ipynb — original notebook with typo fixes, heading hierarchy, MyST citations, and cross-reference links
  - {BALLPARK}_subsequent-literature.ipynb — subsequent literature with MyST citations
  - self.bib, references.bib, subsequent-literature.bib
  - myst.yml with TOC and bibliography configuration ```
Click Create pull request

If you already have an open PR from this branch, pushing updates it automatically — no new PR needed.

Step 11. Record your PR URL

Copy the URL of your pull request (e.g., https://github.com/econ-ark/ballpark/pull/42).

Bring this URL to class — you’ll need to share it.

What Your Folder Should Look Like When You’re Done

{BALLPARK}/
├── [original-notebook].ipynb                      ← original (unchanged)
├── {BALLPARK}_summary.ipynb                         ← your copy (edited)
├── {BALLPARK}_intro.ipynb                           ← new
├── {BALLPARK}_prior-literature.ipynb                ← new
├── {BALLPARK}_subsequent-literature.ipynb           ← new
├── self.bib                                       ← new (the subject paper)
├── references.bib                                 ← prior literature
├── subsequent-literature.bib                      ← subsequent literature
└── myst.yml                                       ← new (TOC + bibliography config)

Deliverable

Four notebooks: _intro, _prior-literature, _summary, _subsequent-literature
self.bib, references.bib, subsequent-literature.bib
myst.yml with TOC and bibliography configuration
Working build with resolved citations
PR URL

Verification

Your PR is successful if:

The PR appears on https://github.com/econ-ark/ballpark/pulls
The PR shows all four notebooks, myst.yml, self.bib, and .bib files
There are no merge conflicts
myst build ran without citation errors

Troubleshooting

Citations don’t resolve:

The citation key must match an entry in self.bib, references.bib, or subsequent-literature.bib exactly (case-sensitive)
Verify all three .bib files are listed in myst.yml under project: bibliography:

myst build fails:

Ensure MyST CLI is installed: myst --version
Run from the correct directory (paper folder, not repo root)
Re-run bash scripts/setup_env.sh if needed

“Permission denied” when pushing:

Make sure you’re pushing to your fork, not to econ-ark/ballpark
Check git remote -v — origin should point to your fork

Push rejected (“non-fast-forward”):

Someone may have updated the branch. Try:

git pull --rebase origin <your-PR-branch>
git push origin <your-PR-branch>

“Merge conflicts” on the PR:

This can happen if someone else edited the same file
Ask for help in class — we’ll resolve it together

Branch or remote confusion:

Run git remote -v and git branch --show-current to see where you are
Ask Cursor: “My git remote -v shows [paste output]. Am I pushing to the right place?”

If You Get Stuck

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

What happens next

Your PR will be reviewed. Once approved and merged, you’ll officially be a contributor to the Econ-ARK ballpark repository!