Opacity/complexities of the Marp architecture: why not unify it?

[sbibauw]

Hi @yhatt. I just wanted to contribute some ideas about the Marp architecture.

As you said in another thread, "it would be not good design if recognizing this architecture was required to all of Marp users". I must say that I've been using Marp for 2 years now, using it mostly from VSCode and sometimes with Marp-CLI, and I still get very confused about where I should put issues/discussions, because I'm still unsure about the differences between Marpit and Marp-Core, about what is there and what is in CLI/VSCode.

As you seem to be worried about adoption and Github stars, I also want to emphasize that I believe that Marp is really superior to most other Markdown-based presentation software: as mentioned by @Juanvvc here in Spanish, VSCode plugin makes Marp much faster & easier to write than Reveal.js, it's easier to adopt for non-developers, much more efficient than software which builds an entire environment for every slide deck, and globally, Marp is the fastest for writing a presentation. So why does it have fewer stars on Github than Slidev, Spectacle, Fusuma...? My guess is that the first look at the Github repo is quite confusing: you get the general Marp repo, then 2 processors, 1 CLI, 1 VSCode plugin, plus other stuff, and so people loose it there.

It's great that you refactored the docs website and made it clearer for newcomers, but many users are coming from Github. Having 5 different repos is causing you to loose newcomers AND to dilute stars among the 5 repos... My point is: having an "empty" repo as you main repo is counterproductive for you and counterintuitive for users.

My recommendation would be to unify the repos as much as possible. Of course, the architecture will remain the same internally for you and for developers, but you could very well try to present them within a single repo. Or have a single main Marp repo, which serves for almost all purposes (readme, issues, discussion, docs...), (so, similar to the marp-team/marp repo now BUT) which does also include the most important piece of code (is that Marp for VSCode? Marp-CLI? Marp-Core? Marpit? Can't you merge Marp-Core and Marpit by the way? the distinction between the two remains completely obscure for me).

At the same time, offer a single "Get started" recommendation for new users. In my opinion, it should be: → Install Marp for VSCode. Then, you can have advanced documentation which explains how to use Marp-CLI to do more advanced stuff. And only talk about Marpit/Marp-Core to developers (but even to them, it would be so much easier if it was only 1 tool, not 2!).

As an example, Dendron is also a complex tool built around a VSCode plugin. They have many different tools, but to newcomers like me, from their website and their Github repo, it looks (at first sight) as if that was only one tool.

[Juanvvc]

I've been invoked!

When I wrote that sentence ("Marp is faster during the preparation phase, RevealJS is easier during the presentation phase"), I was still trying to decide which system was best for my workflow. Since then, I've decided that the productivity of the combination Marp+VSCode beats any other of the systems I've tested, and I have already presented ~50 times using Marp slides. Marp is even better after some custom CSS classes for common layouts: two columns, results, stories... Animations between slides would be a nice feature, and I know they are already supported in Chrome.

The only thing I really miss is the ability to have extra/vertical/hidden slides, because I like to have some slides prepared in case I need to explain some concept further. I opened issue #162 in this regard, with little luck 😁

Regards

[sbibauw]

Hi Juan. Thanks for your answer! Yes, I discovered your crypo slides and your tutorial one, where I found great ideas. I also felt really happy to see confirmations of my own impressions as a non-developer (on Marp vs Reveal.js among other things). I'm always interested in comparing tools, but the markdown-based presentation generators scene is kind of overwhelming, so I'm super happy to see that it's not just me who thinks that Marp is among the fastest and most effective, if not THE most effective.

[Juanvvc]

BTW, the presentation you link is my tutorial / documentation / cheatsheet / theme tester for Marp. Notice the project includes three different themes: my company and two universities. Every slide introduces a new technique just to show what is possible, not what I would use. A real presentation won't use most of the techniques explained in those slides!

A real presentation using one of these themes is my undergraduate course on cryptography (~15 hours) : https://juanvvc.github.io/crypto/slides/index.html

[sbibauw]

Loved your special lists and your whiteboard JS solution!
Actually, I think that we miss a central place for sharing Marp themes/templates (I also miss more examples of good/advanced Marp themes and presentations to get more ideas from). So your repo was really helpful!

[yhatt]

Thanks for your detailed suggestions. 🤓
It can generalize your suggestion into the common problem "Monorepo vs multi-repo (manyrepo)". This has already discussed in everywhere: Neither is a silver bullet.

In the beginning of marp-team/marp repository, it had been expected to act as a monorepo repository to store every Marp projects. However, this repository has been renovated as the entrance because we had met some concerns to manage our projects.

First, let me explain why I have decided to split into multiple repositories... The classic Marp had an "all-in-one" repository (https://github.com/yhatt/marp), as you have suggested. It had worked well for a while, but people have wanted various features and raised a lot of issues. I had drown in the tidal wave of many requests and lost what Marp aimed to. As a result, I had burned out for about a year. I could not do any actions for Marp during this period. This situation could easily happen in the open-sourced project, and it would become to sad for everyone in the most cases.

When rebooted Marp, I made clear the boundary of project scope for each libraries and tools as the repository. Marp team has common understanding like "what Marp-XXX aims to and not to" for each repositories. The existance of them is a reason why the current Marp keeps a maintainabiilty for the long live. If it had been a single project again, we may have met increasing maintainance cost due to the scope creep, and have brought the same unhappy situation as the classic Marp.

Then, let me see the monorepos architecutre in more general eyes. As you suggested, monorepo would become easy to dive into our projects for outside contributors. Everyone is in a repository, and it would not lead any confusions about a report line.

On the other hand, thinking about the point of view from a maintainer is also important. Monorepo requires to build a complex CI workflow to cover each projects that have different lifecycles. In addition, the maintainer (or moderator from community) need to sort reported issues/discussions that includes mixed scopes.

Besides, we are just a team. If a developer joins to our team, there is a secuirty risk in what the authority of GitHub users to commit and release cannot control per projects.

The development of Marp is just by a volunteer (me), and not leads by any people, companies, and organizations. For keeping long-live and maintanable structure, I have to make minimize a burden of maintainer. Thus, the motivation to merge repositories into one is weak.

I apologize for making confusable architectures, but switching the repository structure will not change the actual architecture (Marpit = Framework for general purpose / Marp Core = Core of our brand / Marp CLI = CLI frontend / Marp for VS Code = GUI frontend) so we have low priority than working on other useful features. About stargazers, surely I sometimes mentioned to stars as a useful metric of GitHub projects, but the wise consumer ought to have recognized the number of stars does not point the popularlity directly.

[sbibauw]

Thanks for your long answer. I get your point.
Even then, I'd say that one already helpful action would be to include one of the repos in the main marp repo. Probably either Marp for VSCode (because it's what you want new users to install) or Marp-Core (if that's your core business). I'd personally recommend putting Marp for VSCode here. This way, when people star it or watch it, they get the new releases of Marp for VSCode (rather than an empty/website-only repo with no releases, no issues, etc.).
But then, if you believe that's not a good idea, don't worry. You're definitely right about the struggles of keeping the effort and maintenance on the long-term for a single, voluntary developer, so thank you so much for keeping up with the great work! Everything that helps you keeping it up is the way to go! :-)

[yhatt]

I've just found there is a hybrid solution called "meta repository": gets monorepo advantage together with keeping multi repos. I don't know this solution matches your suggestion but it may be worth to explore.

• Mono-repo or multi-repo? Why choose one, when you can have both? | by Patrick Lee Scott | Medium
• mateodelnorte/meta: tool for turning many repos into a meta repo. why choose many repos or a monolithic repo, when you can have both with a meta repo?

[sbibauw]

It looks great, yes! Basically, unifying the looks of it under a single, at-first-sight unique repo for newcomers would be ideal!

[yhatt]

At the same time, offer a single "Get started" recommendation for new users. In my opinion, it should be: → Install Marp for VSCode. Then, you can have advanced documentation which explains how to use Marp-CLI to do more advanced stuff. And only talk about Marpit/Marp-Core to developers (but even to them, it would be so much easier if it was only 1 tool, not 2!).

I agree this. We have designed Marp for VS Code for beginners and moderate users, Marp CLI for advanced users, and Marp Core for developers. README.md in marp-team/marp is explaining in bottom-up by historical reason, but top-down approach is better for end users.

Marpit framework is actually independent project from Marp, so it may not need to mention when the unified document has mentioned to Marpit specific features.