Separate math macros file

[alanlujan91]

Which area is this feature request for?

MyST Markdown Syntax

Describe the feature you'd like to request

I have a huge list of latex macros defined on my myst.yml file under math:. I would like to be able to define these on a separate file, such as math_macros.yml that I could reference in my myst.yml config file instead of having the list in it.

This could also allow me to organize my macros better by adding comments and some separation between different types of macros.

Describe the solution you'd like

No response

Describe alternatives you've considered

No response

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[rowanc1]

Thanks @alanlujan91! This is really cool, and can mean that these are shared between projects pretty easily as well. The LaTeX writing as well as the HTML only pulls in the macros that you use, which I quite like -- meaning if you submit the source to arXiv or something, you get a concise set of macros at the top of the LaTeX file of only the macros that you used.

@fwkoch I think that we could do this if the math macros is a string (and exists on disk or remotely)? I think the one thing that we need to look out for is that we don't make myst-frontmatter dependent on running from the filesystem or on fetch behaviour (needs to run in a browser as well). That could be done by passing in a function that can resolve files, and might take a bit of thought beyond this specific use case. Any thoughts on that?

[agoose77]

@rowanc1 this might be where you're thinking already, but maybe this can be a project-like property? That way, per-file properties are defined externally, and per-file macros are defined in the particular file frontmatter.

[rowanc1]

Yes, totally! I think this probably would make the most sense on the project. The way that citations work is that you can define on the project, and then layer in per-file bibliographies. I think that makes sense for this feature as well. You might want to use your lab-groups macros in general, but add a few extra ones for a specific file.

I think that also might mean that this could be a list of strings/files/urls well.

e.g.

math: my_lab_group_macros.yml
# or
math:
  - my_lab_group_macros.yml
  - my_custom_macros.yml
# or
math:
  '\dobs': '\mathbf{d}_\text{obs}'

I think in all cases these resolve to a single dictionary, and also warn if there are things that get over-written.

When we are changing this we should also think about #280, which allows for optional arguments in the macros.

[fwkoch]

Should we do this in a non-math specific way? i.e. just specify external frontmatter file(s) that combine together? We already do this for page frontmatter, with fallback logic to fill in fields from project frontmatter. We would need slightly different logic to combine these, but then we could basically include any number of frontmatter files. So something like:

title: My Article
authors:
  - name: Jane Doe
include:
  - my_lab_group_macros.yml
  - my_custom_macros.yml
  - https://example.university.edu/data/myst_licenense.yml
  - lab_group_authors.yml

[rowanc1]

I really like that idea, and we do already do this with site/project/page frontmatter, it is just adding a few new ways of bringing that in (I think we will also have to tweak the math side a bit). The potential for reuse and some standardization of these components is pretty high.

[fwkoch]

This is now supported with #1215 and #1251 - you may specify a yml file with only math macros, which follows the same myst.yml format:

# math_macros.yml
version: 1
project:
  math:
    '\dobs': '\mathbf{d}_\text{obs}'
    ...

Then you may reference this in another myst.yml file

# myst.yml
version: 1
extends:
  - math_macros.yml
...

The entries referenced under extends may also be URLs to remote files.

The only additional step related to this is #1308 - that will allow math_macros.yml to have a simpler structure (probably just math as a top-level key). But I think the currently released functionality is enough to consider this closed.