📖 Contributing a new features to MyST (roles & transforms)

[agoose77]

This PR will eventually add a new page to our documentation, that intends to act as a "ten minute guide to adding new features to MyST". It will overlap with the plugins page slightly, but I hope that it will bootstrap some of the contribution questions.

[rowanc1]

Very excited about this - thanks for getting it started @agoose77!

[agoose77]

@rowanc1 I think this is ready for a review pass. I'm sure it's not perfect, but I'd benefit from a fresh pair of eyes 🙏

[LecrisUT]

Do you think it's worth adding to this PR how to add a frontmatter option, or should it be added in another tutorial? The frontmatter option seems quite a bit more convoluted to document.

[agoose77]

Do you think it's worth adding to this PR how to add a frontmatter option, or should it be added in another tutorial? The frontmatter option seems quite a bit more convoluted to document.

Hmm, it's a tricky balance between covering "enough" and "too much". I want to keep this tutorial / guide small enough that someone could feel brave enough to get started. I think we might need more guides to help cover the wider challenges with contribution.

[LecrisUT]

Do you think it's worth adding to this PR how to add a frontmatter option, or should it be added in another tutorial? The frontmatter option seems quite a bit more convoluted to document.

Hmm, it's a tricky balance between covering "enough" and "too much". I want to keep this tutorial / guide small enough that someone could feel brave enough to get started. I think we might need more guides to help cover the wider challenges with contribution.

Indeed, I probably confused role with directive, so adding those parts to this documentation, would be a bit too much. Maybe the directive can be intuited a bit after this guide, but frontmatter seems to be more complicated, e.g. my attempts at navigating #979. Worth having an example for that imo.

[rowanc1]

I have gone through this and updated a few things!

This is great @agoose77 and I think ready to be merged. I changed it so we transform the wordCount node to a text node so that the final picture is complete. There can be another tutorial in the future on how to add a new renderer.