jupyter-book/mystmd

Improve templating for docx export from myst-cli

fwkoch opened this issue · 3 comments

fwkoch commented

Context

  • myst-cli has introduced functionality to export myst files as tex/pdf/docx from the command line
  • tex/pdf exports allow you to specify a latex template to customize the output. There are already a number of templates available: https://github.com/myst-templates. These are totally standalone, with a template.yml config (defining template metadata, required frontmatter fields, and additional template options), a nunjuks-style template to use, and all additional supplementary files (icons, latex document classes, etc).
  • jtex validates user input against the template options and fills in the template based on these options, myst frontmatter, and tex content (converted with myst-to-tex)
  • docx templating, however, requires passing in a renderer function (since we use docx to generate the document). It can take additional template options (and these can be defined in a template.yml file), but there is nothing like jtex validating these options and holding it all together.
  • Additionally, there is no easy way to define additional static files required by the renderer...

Proposal

  • I don't think we should move away from using the docx library for now. This would require writing valid docx nunjuks-style templates in XML, doesn't feel great, but certainly a future possibility.
  • For now it would be great to at least:
    • validate options based on a template.yml
    • bundle static files together with the template.yml
    • connect this template to the renderer function so they are used together
  • This means teasing apart the template download / validation part of jtex from the tex-specific rendering, and updating the docx build to consume a template package using the non-tex part of jtex.

Tasks and updates

No response

rowanc1 commented

Some other things that I noticed after the merge is that the current docx template still has a curvenote footer on it. We should fix that up and provide some extensibility there.

  • 👍1
rowanc1 commented

Parts of this have been addressed in #67, I think we still need another pass of moving parts from jtex --> myst-templates

rowanc1 commented

With the addition of SVG conversion, this is now complete!

The docx template is here:
https://github.com/myst-templates/docx_default