[In progress] The unified documentation for Marp

[yhatt]

As mentioned at https://marp.app/blog/re-creation-of-marp-website, our documentations are scattered to many repos and making confusion when learning overall of Marp.

We're working for the unified documentation hosted in marp.app. Many pages are a stub and not yet ready for public but you can peek docs working in progress at https://marp.app/docs/.

[pierre-haessig]

This looks great! Indeed, as a occasional but regularly returning user of Marp, it's sometimes difficult to dig into advanced topics like theme customization or custom themes. The new docs are promising.

Now, I've just discovered the pretty useful color customization of Gaia and Uncover themes from PR #221 and I wonder what is the best place to put the documentation fragment that you put in the PR:

• in the existing doc about Marpit directives, themes section https://marpit.marp.app/directives?id=theme?
• or in the new theme guide https://marp.app/docs/guide/theme ?
• somewhere else?

[yhatt]

I hope to put it in the new theme guide. I want to contain an extensive guide in the new one.
https://github.com/marp-team/marp/blob/main/website/docs/guide/theme.md

NOTE: In the near future, the guide would update by the change of marp-team/marp-core#244. (!important will be no longer required)

An important thing for thinking about this is that we are essentially thinking about Marpit and Marp separately. Marpit's documentation is targeted at "developers using the framework", and we have not assumed reading by Marp consumers, On the other hand, the new guide is targeted to consumers.

[pierre-haessig]

I've been experimenting on drawing a global map of the Marp ecosystem to guide newcomers. This is in the same spirit of the https://marp.app/ homepage, but with explicit links.

This is the link to the source for Diagrams.net: https://gist.github.com/pierre-haessig/e936294d2bb70514376ed952df2d4a44

This is a first draft. Let me know what you think (that is: is it worth polishing?).

PNG export (for some reason, the Marp logo on top is not exported)

[yhatt]

Looks awesome! This diagram would help project contributors to know the architecture. 😄
We already have a simple diagram for that in the contributing guideline of marp-team projects, but this diagram is showing the current architecture clearer.

Of course, we accept the pull request to update "Architecture" section: https://github.com/marp-team/.github. FYI making separate ARCHITECTURE.md is also good option.
https://matklad.github.io//2021/02/06/ARCHITECTURE.md.html

On the other hand, it would be not good design if recognizing this architecture was required to all of Marp users. If the new guide has mentioned to this diagram, it would have to be for advanced and developers. (At the same time, all of features in the ecosystem should be covered in the new docs)

[chenxizhang]

very nice

[spkane]

@yhatt I am just wondering if there has been any progress on providing documentation for custom theme generation that is more user/consumer orientated than the current documentation? Maybe a blog post or the like that covers this.

I am interested in creating a new theme for Marp for my work, but CSS is not my strong point. Although I have been able to tweak one of the themes for my needs, I'd like to have someone create a new theme for my use case and some good documentation would be very useful (at least for the things that are more unique to Marpkit).

[yhatt]

In Marpit, styling the slide with CSS has no unique/specific features than CSS for the web. So we believe that existing materials for learning CSS in the world are still useful. Even if we had written an article, I do not think there would be anything new about CSS styling.

Marp's theming system (extended Marpit, and provided by Marp Core) may have value for writing an article, but it is too advanced part and most consumers should not need to care about it.

And I'm not a native English speaker, so writing natural articles and docs for non-developers is more painful than you might think. I always bet on the spirit of open source: writing documentation and articles is also a way to contribute to us.
https://opensource.guide/how-to-contribute/#what-it-means-to-contribute

[spkane]

Thank you for the reply. That makes sense. I'll likely fork one of the existing themes, maybe Gaia, and try to create some new CSS from there.