Markdown format nr. 3

[silvester-pari]

Using the package from quarto did not work out in the end, so we can come up with our entirely custom syntax.

This third approach is a kind of "Mix" between the two older approaches. It relies on a markdown-it plugin (old, but still working) https://github.com/rstacruz/markdown-it-decorate.

By passing attributes inside HTML comments and some additional rules, it allows creating a completely "clean looking" md file when rendered by GitHub (check the rich diff of the added file), but at the same time allowing to create all needed configs for our storytelling needs (I hope).

If this is agreed upon, the proposed roadmap for upcoming implementation would be:

• [ ] implement markdown-it-decorate (or any more up-to-date replacement, or own fork)
• [ ] implement section rendering + nav rendering for external md files
• [ ] implement eox-map section (tour mode) for external md files

This should give us some basic experience with which we can decide on how to continue (updating the editor, editor snippets, more sections etc.)

[srijitcoder]

@silvester-pari This approach and markdown look better to me compared to the one you shared earlier. We can start with the roadmap once everyone agrees with the approach and markdown.

[santilland]

This proposal feels quite clean and understandable. One thing that could be considered strange is that h1(#) and h3(###) have "special" functions but h2 does. So i'm not sure about using h3 as step definition, it renders nicely in vanilla md, so i can't think of a better alternative. So from my side also thumbs up

[silvester-pari]

Yes, that's a bit less ideal, the problem is that GitHub (and other renderers) renders h1 and h2 with an underline, but everything starting from h3 doesn't have one. I think this is also one reason that quarto uses h2 as sections, and h3 as sub-sections/steps. We can also do h1 + h2 and see how it looks like, I hope it is not too much effort to switch between h2/h3 in the parser.

[lubojr]

I am also in favor of this approach. I can see this format being both manually editable and readable in GitHub in the best manner possible.