Document expected pandoc version

[notmatthancock]

A pandoc version too old can result in type errors (e.g., I encountered the pandoc python package being unaware of the Caption type), and a pandoc version too new (> 3?) will not be compatible with the pandoc python package. We should document the expected pandoc version range (or specific version). I found that 2.19.2 seemed to work.

[notmatthancock]

the docs do mention this but I missed it

[joshuatz]

FWIW, even with the exact version documented, I think there is still room for improvement, where N2Y could allow a user to override the pandoc path / executable that they want to use. This way you don't have to globally install the old version of pandoc to get N2Y to work.

Because of the way the imports are resolved and plumbum inits itself / parses the PATH, doing this right now requires a very specific import order and path monkey-patching. This is what I used on another project:

# Note: PATH monkey-patching has to be done _before_ N2Y imports (or pandoc lib), in order
# for them to make it into the plumbum resolution layer, which the pandoc
# wrapper python library uses for shelling out.
# Having this override is useful because currently N2Y requires a much older
# version of Pandoc, and one might not want to make that their global default
PANDOC_PATH_OVERRIDE = os.getenv("PANDOC_PATH_OVERRIDE")
if PANDOC_PATH_OVERRIDE:
    root_logger.debug("🔗 Pandoc path was overwritten, based on env var")
    os.environ["PATH"] = f"{PANDOC_PATH_OVERRIDE}:{os.environ['PATH']}"

import pandoc
# Now we can import n2y stuff
from n2y.export import export_page 

N2Y could even add an automated installer for the old version of pandoc, or even just vendor in the files, and then force plumbum to find the local install instead of using the user's global pandoc version.