expose firstTimeLong to project settings

[jan-david-fischbach]

To be able to use firstTimeLong in MyST projects...

[jan-david-fischbach]

@rowanc1 while working on this I was struggeling a bit with npm run dev of mystmd: It doesn't seem to update continuously. Instead I seem to have to run after every change:

npm run build
npm run dev

[rowanc1]

Thanks @jan-david-fischbach!!

@fwkoch do you think you could take a look at this and help get it in? My first thought is that we should have a configuration for MyST parsing, configuration etc. maybe a stand-alone myst object or something? As well as establish some naming conventions.

Most of our frontmatter at the moment is around author/attribution etc. and we don't have any on configuration of the CLI/parser itself yet. I think this (maybe) needs a bit of thought to establish a new pattern for these sorts of things.

[jan-david-fischbach]

Hi @rowanc1, thanks for taking care. I also thought that the way I solved it now might not be the ideal "workflow" for new options. Maybe we could establish a front matter field pluginOptions (or similar) where either an unvalidated list of options can be included, that can voluntarily be considered by plugins etc. Or a "per plugin" configuration, that is validated according to a validator provided by the plugin.

[rowanc1]

Yeah, I really like that idea, where you can pass options for transforms/plugins and that allows other people to extend this in the future. This level of extensibility has been a common request in jupyterlab-myst as well, which we have been working on with @agoose77. Something like:

plugins:
  abbreviations:
     firstTimeLong: true
  dollarmath: false
  tasklist: false

Where each config corresponds to some sort of plugin, which in the future will hopefully be a bit better defined, but right now are basically the directives/roles + transforms + user interface.

[jan-david-fischbach]

Would that also involve a standardized way to define new roles/directives? Roles always only have one input, correct?

[fwkoch]

Thanks for the PR!

New roles and directives are defined declaratively (you can see a bunch of examples in the myst-roles, myst-directives, and myst-ext-* packages) - these define how you go from role body and directive arguments/options/body to mdast nodes. They also provide validation on the role/directive content itself. However, there is no plugin ability yet to add new roles/directives to myst dynamically; the closest we get is adding them to the CLI here: https://github.com/executablebooks/mystmd/blob/main/packages/myst-cli/src/process/myst.ts#L18-L26 - nor are there existing examples of passing configuration options to these at a project level, as your PR is doing.

I'd like to give a bit more thought to how these plugins might work, in the context of this PR - I'll try to get some coherent feedback to you next week.

[jan-david-fischbach]

Hey @fwkoch,
any new ideas yet?

[rowanc1]

@jan-david-fischbach I have started to implement plugins in #617 as a "standardized way to define new roles/directives" as you mentioned. I think that parser might actually be a better top-level key in the myst.yml for turning various parts of the parser on/off. I haven't thought through how to surface settings yet, if you have ideas based on the first sketch in #617 I would love you input!

Sorry for the slow movement on this -- I was on paternity leave and @fwkoch was picking up the slack from my day-job! I am coming back online, so hoping to start moving on these PRs again.