Initial draft of myst-spec and Javascript announcements.

[rowanc1]

@chrisjsewell @fwkoch and I are working on a release of a MyST parser in JS (mystjs and unified-myst), and the beginnings of a MyST spec (jupyter-book/myst-spec#1) and standardized AST (based on mdast) which is starting to come together, and will likely be ready for a v1 in the next few weeks (right @chrisjsewell?!). The v1 spec formalizes what we have today, and ensures that the JS and Python pieces work the same.

In #538 there was talk of a blog post that gives this some top-level attention that we can post around the place and let people know what we are up to. There is a ton of great work going on, and we need to tell people about it. :)

The post is still a little bit ahead of where we are today. It also might need to be broken up regarding the "MyST enhancement proposals", which will probably be more appropriate as we improve the spec and implementations after a v1 release. There are some future-looking links to https://myst.tools (which @choldgraf bought for the organization about a month or so ago in team meeting.

TODOS:

• Make spec.myst.tools live
• Create a wrapper site for myst.tools that have links to the various places (myst-parser is the most complete here)
• Figure out a plan for other documentation moving around (open an issue in meta)
• Introduce documentation at js.myst.tools that incorporates the mystjs/unified-myst work (or points to the right places)
• Update specifics about unit tests, numbers, etc in the blog
• Test links
• Figure out how to get the blog to actually show in the list?!
• 🚀

[welcome]

Thanks for submitting your first pull request! You are awesome! 🤗

If you haven't done so already, check out EBP's Code of Conduct and our Contributing Guide, as this will greatly help the review process.

Welcome to the EBP community! 🎉

[chrisjsewell]

Cheers @rowanc1, as you mention, will hold off on a review until I'm a little further down the line

and will likely be ready for a v1 in the next few weeks (right @chrisjsewell?!)

Slow and steady wins the race 😛 But yeh I hope so, and pushing as quick as possible 😅 https://github.com/executablebooks/unified-myst/graphs/contributors

[rowanc1]

Sounds good, I didn't mean to say that the whole unified stuff was done, just aiming to settle down most of the thinking around an initial release of some of the namings in the spec! From our convo today, it seems like the major decisions are settling down at least. :)

[chrisjsewell]

I didn't mean to say that the whole unified stuff was done, just aiming to settle down most of the thinking around an initial release of some of the namings in the spec!

Oh absolutely, it doesn't have to be v1.0 or anything, but it does need to be able to "generate" the myst spec.
I very much feel that a spec needs a good reference implementation, to ensure it is something that can actually be implemented 😅
(and at least initially, in a way that is compatible with docutils -> sphinx -> myst-parser -> jupyter-book, whilst still striving to improve on that)

As you say though, we are gradually getting there, as I'm "feeding back" the implementation into the spec: jupyter-book/myst-spec#39

[stevejpurves]

this blog post already went out? / this PR can be closed?

[choldgraf]

My feeling is that this post can reduce some of it's content that is now redundant w the other post (like the announcement of mystjs) but the technical description of the spec, ast, ideas on unified, etc would still certainly be of interest to folks. So perhaps this post can go into more detail than the other one did, and describe the structural and technical foundations that we are laying. Maybe it could also be motivated by some of the recent work @rowanc1 has been doing on JATS outputs and "mystjs outputs as data structures that can be reused elsewhere"?

[rowanc1]

Yes, I think it needs a pretty serious overhaul, but there is some of this that hasn't gone out!

I will overhaul it and get something out of the text here. :)

Glad the first blog is out!!!

[rowanc1]

Closing this! The spirit of it was revamped in #936.