Gatsby: Per-file custom LaTeX macros in gatsby-remark-katex

[janosh]

It's currently possible to specify custom macros in the package options as suggested in #11320.

{
  resolve: `gatsby-remark-katex`,
  options: {
    macros: {
      "\\expec": `\\langle #1\\rangle`,
    },
  },
}

However, there doesn't seem to be a way to define \newcommands on per-markdown-file level (or am I missing something)? Would this functionality be difficult to add?

[wardpeet]

It's not possible to do it on a file based level, can I ask why you want this feature? Why won't this macro work for all files?

[janosh]

I usually have macros that are very specific to certain topics and hence files. In those cases, I feel it would be cleaner to define those macros directly in the file that uses them. It's rare that they would cause problems in other files although that can happen too. For instance, sometimes you want to implement the same macro differently in different contexts. An example of that would be LaTeX's default overset arrow notation for vectors which is probably more easily recognized as vectors by non-scientific readers. In most cases, however, I would want to change to the more common boldface upright notation \renewcommand\vec{{\mathbf{#1}}}.

Another drawback that comes with specifying macros in gatsby-config is that you have to recompile the site every time you add a new one.

[wardpeet]

sadly we do not support it and I don't think we want to support this. This feature is pretty niche and we suggest using different macros or fixing these things inside your latex macro itself.

i'll let some other chime in as I'm not super familiar with md (remark).

[geyang]

this is very disappointing. Feedbacks from the community like this is a chance to open up to niche use case as Gatsby goes main stream. In aggregate, it is likely that every user is going to run into one of these long-tail use cases.

[janosh]

@episodeyang Maybe upvote the issue and if enough people do likewise it might be reopened.

[geyang]

yeah thanks @janosh, just upvoted. I just moved to London!

[wardpeet]

We're happy to take Pull requests for this feature if you're up for it.

[janosh]

This is slightly embarrassing. I just skimmed through the KaTeX docs (which I should have done way sooner) only to discover that KaTeX already supports this use case... almost.

You can use \gdef (or equivalently \global\def) to define macros that KaTeX persists between math expressions. I.e. writing $\gdef\foo{x^2}$ at the start of a markdown file will let you use $\foo$ all throughout that file.

I said almost above because this actually modifies KaTeX's macros object in-place and hence will affect your entire site. So this won't allow to make a given macro behave differently in different documents. If you redefine \foo somewhere else on your site, all instances will adopt whichever definition is parsed last. But at least it let's you - if you so desire - define macros close to where they are used.