MyST MD - Infrastructure Project (review and issues)

[mmcky]

This is a place to discuss the QuantEcon Lecture Improvements Project (migration to MystMD backend).

QuantEcon is working closely with Curvenote to develop and improve the MySTMD infrastructure to enable QuantEcon to migrate to a MystMD backend. This project largely consists of development of a QuantEcon Theme, enabling the PDF to be built and associated improvements to the software stack to enable this that can benefit the broader open-science community.

Project Review + Feedback 20th February 2025

Thanks to the Curvenote team for the excellent work to get us to this point. Below are some feedback points based on a team review of current project outputs. It is exciting to see this project come together.

QuantEcon Theme (HTML)

• (bug) some tables in dark mode become hard to read due to line formatting
  

• figure labels should be centred and a bit larger

• Chapter titles could be more compact with the lecture title to follow the series title such as

• (style) It looks like the new system is not using Pygments based highlighting for Python syntax. It is a different colour set to the one used on the current site.

• code blocks background is a slight shade of grey to let it stand apart from the text in our current theme

• more minimal style for notes has been adopted to make it less intrusive to the reading experience

• (development) missing directive support for tableofcontents and only

• (feature idea) Would it be possible to have tabs to show the code behind an image for a more compact presentation?

PDF

• (feature request) - enable page numbers for pdf file
• (tables) there are some issues with number formatting. Some tables include numbers that make the table unreadable such as on Page 21 just above 2.1.3.
• (feature request) - formatted front page

• (feature request) - inclusion of parts concept in Table of Contents and Book style PDF
• (feature request) - inclusion of formatting options around chapter

• (bug) solution blocks may be constrained to single page causing content overruns? An example is Solution Block 13.57. Perhaps the solution block does not extend to the next page when it includes code blocks and images; instead, it overflows the page margin (e.g., Solutions 6.20, 6.22, 6.25, and 6.26). (is there a similar concept to breakable in tcolorbox from LaTeX in typst)

• (bug) references is currently numbered as its own chapter. It would be nice to have just an unnumbered Reference or bibliography section.
• (feature request) enable simpler more minimal styling for sphinx-exercise / sphinx-proof type blocks that include a single line of colour rather than a full background colour in the title box. (See

Reference PDF is here: quantecon-python-intro.pdf

[mmcky]

@kp992 this is a review I did with Curvenote re: mystmd. Perhaps you could look through this and see if these issues are still present in the current version being used on lecture-python-programming migration.