[RFC] The future plan of Marpit (delayed)

[yhatt]

This is a RFC (Request for Comments) document for next major version of Marpit and the content may change.

Do you have interested in the future of Marpit? We always think listening opinions from Marp / Marpit community is the best rather than working with our dogmatic decision. We want your feedback for keeping to evolve Marp ecosystem! 💬

---

UPDATE: Following plans are delayed after v2.

---

Marpit has reached stable v1 in May 2019. And this is a roadmap to the next stable.

Marpit v2 in the future focuses to the enhancement as more universal framework for creating slide deck. We hope to make a basis of extensibility that is applicable not only to Marp ecosystem but also to other popular slide frameworks, reveal.js, WebSlides, and so on.

Perhaps v2 the future version of Marpit would be full-rewritten, but most of features and syntax won't change unlike Marp -> Marp Next.

Rename project

At first, we have to explain planning to rename project.

Marpit was a coined word named from Marp and "it" suffix, in honor of markdown-it library. However, we found that "marpit" has a violent meaning in Hindi.

Project name is important. We fear that some people are keeping a distance from our project just by the image of name. So we think Marpit should change the name into a word which remind no special meanings.

Moving to TypeScript (#136)

Marpit is an only project built on JavaScript (ECMAScript) in our mainstream projects. Marpit's type definition is defined in /index.d.ts but it's hard to maintain together with JS.

Usefullness of TS has already proved in other projects. By moving to TS, developer experience will improve not only for Marpit but also for plugins.

UPDATE: TS migration is going to start from v2 step by step. v2 will allow remaining JS by allowJs: true.

Choose Markdown parser and make clear specification for plugin

For common Marp user, an internal parser is not too important. On the other hand, user that getting annoyed for lacked syntax in CommonMark have to consider using plugin to extend syntax.

Marpit aims to the extensible framework by plugins, and hopes to spread plugin ecosystem. However, unfortunately Marpit v1 plugin by community is hardly created and used yet.

We think currently the support for plugin author is very weak. For example, the specification document of Marpit tokens (AST) has not provided at the moment. In addition, we think restrictions by parser's architecture may make plugin development harder.

v2 will be the best timing if Marpit replaces a parser and specification into a promising.

markdown-it

Currently Marpit v1 is using markdown-it as our base parser. It is working over the years, well-maintained, and easy to extend through plugins.

However, there are some restrictions that come from its architecture:

• Cannot use async functions while parsing (In fact prevents implementing #135)
• There is not character-level source mapping

Nevertheless, using markdown-it parser continuously in Marpit v2 might be OK. Marpit v1's core implementations are very stable, tokens with plain structure are easy to extend, and not required cons shown in above anyway. If the specification is well-documented, it may have no problem for plugin author.

remark

remark (NOT Markdown presentation template) is a modern and popular parser without above restrictions. In fact, some tools that have same purpose of Marp are supporting remark.

• mdx-deck, for creating slide deck based on MDX parser extended from remark, is earned 8k stars about the same of outdated Marp app.
• According to recent trending, fusuma, to create WebSlides based slide deck (3.5k stars), is also powered by remark-based MDX.
• In fact Marp for VS Code is parsing Markdown by remark, to get characeter-level source map for warning.

VS Code's markdown engine is based on markdown-it. So Marp for VS Code might have to change the logic drastically if Marpit moved to remark.

MDX (Based on remark)

About MDX, we are taking a dim view because Marp requires only standard knowledges, such as Markdown, HTML, and CSS. However, actually it's popular in some tools so leaving extensibility for MDX makes a value.

Which is better?

That is the question to Marpit plugin author.

Both parsers have pros and cons. We want to hear an opinion from users interested to develop Marpit plugins.

Get rid of instance dependent parsing

Some internal plugins and classes are dependent on values defined in Marpit instance, such as lastGlobalDirectives, lastComments, lastStyles etc...

We should get rid of them and change to store values to the context object created within render().

Layer for Inline SVG mode

"Layer" is new concept available only in inline SVG mode, to make the layout system generalize.

Marpit v1 has advanced backgrounds to apply complex layout with keeping original DOM structure of Markdown (e.g. Multiple backgrounds, Split slides inspired from Deckset, etc...) They features are not changed in v2 too.

A current problem is too complex parse & build process of them. Leaving these logics may make it difficult to maintain.

As the discussion on #137 shows, the idea of layout using inline SVG is profitable. We have no plans to add that as the built-in feature at present, but we want to be making useful layouts become easy to create in plugin.

In v2 future, we will organize layout system for inline SVG as a new concept "Layer", and make easy to manipulate and extend through Marpit plugin.

Concept

At first, let's review v1's inline SVG rendering.

# Hello, Marpit!

This Markdown will convert into like this:

<svg data-marpit-svg viewBox="0 0 1280 720">
  <foreignObject x="0" y="0" width="1280" height="720">
    <section id="1">
      <h1>Hello, Marpit!</h1>
    </section>
  </foreignObject>
</svg>

When Markdown is using background image(s) through ![bg](), children of <svg> element will have a huge change.

![bg](background-image.jpg)

# Hello, Marpit!

<svg data-marpit-svg viewBox="0 0 1280 720">
  <foreignObject x="0" y="0" width="1280" height="720">
    <section data-marpit-advanced-background="background">
      <div data-marpit-advanced-background-container="true" data-marpit-advanced-background-direction="horizontal">
        <figure style="background-image: url(&quot;background-image.jpg&quot;);"></figure>
      </div>
    </section>
  </foreignObject>

  <foreignObject x="0" y= "0" width="1280" height="720">
    <section id="1" data-marpit-advanced-background="content">
      <h1>Hello, Marpit!</h1>
    </section>
  </foreignObject>

  <foreignObject x="0" y="0" width="1280" height="720" data-marpit-advanced-background="pseudo">
    <section data-marpit-advanced-background="pseudo"></section>
  </foreignObject>
</svg>

Now you can see 3 <foreignObject> elements: for background images, main contents, and pseudo-layer like pagination defined by section::after in theme CSS.

They can define the position and size of content declaratively in DOM, so it becomes easy to control layout such as split slides.

In Marpit v2 for the future, we will treat each <foreignObject> as "Layer" of a slide, and provide interface to add and modify layer contents, position, and stacking orders programatically. (A detailed interface is not defined yet)

Contents layer

Each slide page must have the contents layer for placing original DOM converted from Markdown.

Plugin that provides additional layer will pick required elements from the contents layer, and append them to new layer. For example, advanced background plugin will pick ![bg]() from the contents layer, and append to the background layer.

Layers in regular conversion (v3?)

In addition, we also have an idea for layers in regular conversion by using nested <section>.

<section id="1" data-marpit-layer="true">
  <!-- Layer for background -->
  <aside data-marpit-layer="bg" style="top:0; left:0; width:1280px; height:720px;">
    <figure style="background-image: url(&quot;background-image.jpg&quot;);"></figure>
  </aside>

  <!-- Contents layer -->
  <section style="top:0; left:0; width:1280px; height:720px;">
    <h1>Hello, Marpit!</h1>
  </section>
</section>

We don't think that can realize immediately because it must consider manipulating theme CSS. But if it was realized, Marpit would grow extensibility to other framework, especially reveal.js. By using additional layer(s), Marpit can generate vertical slides for reveal.js.

# Marpit extensibillity for reveal.js

---

## Vertical slides

***

## with layer

<section id="1">
  <h1>Marpit extensibillity for reveal.js</h1>
</section>

<section id="2" data-marpit-layer="true">
  <!-- Contents layer -->
  <section>
    <h2>Vertical slides</h2>
  </section>

  <!-- Additional layer generated by plugin -->
  <section>
    <h2>with layer</h2>
  </section>
</section>

W3C has the public working draft for cascade layers in CSS cascading and inheritance Lv5. It is not meaning to separate styles for contents and we think it's too early to adopt that, but it has a worth to consider for using to style Marpit theme.

Others

• Make PostCSS compiler for theme CSS be pluggable

[yhatt]

Skinny to skeleton

The most of v1 is made for Marp ecosystem. Surely it can use in the other frameworks, but it's like applying monkey patch and the real "pluggable" is far away.

I tried to peel Marpit features one by one and I realised there are only 2 features as a core of our framework: Split out slides by ---, and directives. We have to provide only them "skeleton" features for aim to apply into a lot of frameworks.

The all of v2 features are available as extensions for our skeleton: CSS theming, image syntax, inline SVG mode, and more. They are going to keep as built-in features that can use from a new entrypoint such as marpit/marp.

For the other web slide libraries, Marp team and our community could provide Marpit engine for various frameworks by applying library-specific extensions to skeleton. e.g. marpit/revealjs...

[yhatt]

The time to upgrade Marpit into v2 has come by #260, but unfortunately without discussions! 😭

As I mentioned in our blog, we are going to have to delay or reconsider exist plans.

The new minimal requirements for Marpit v2 are following:

• Moving to TypeScript: Moving to TypeScript #136
  • At least I think Marpit v2 should use TypeScript as same as the other project. It's OK even if using allowJs: TS could not emit type declarations in allowJS mode at the time I have planned v2 first, but now it can.
  • Delated to v3.
• PostCSS 8: Upgrade to PostCSS 8 #260
• Bundle modules with rollup
• Resolve How to except title slide from total number of pages of pagination? #218 Delayed.

See also the milestone of modified v2.

[harsh183]

However, we found that "marpit" has a violent meaning in Hindi.

As a Hindi speaker I never made the connection because the way you pronounce both feels very different to me.

[yhatt]

Thank you for your feedback! I'm relieved to hear that.

The main reason why I feel concerning about the project name is that sometimes there is bad experience during learning Marpit. By googling Marpit, uncomfortable images like group bashing often come into eyes unintentionally.

Especially non Hindi speaker cannot recognize its reason so studying Marpit may become negative feelings to someone.

[harsh183]

By googling Marpit, uncomfortable images like group bashing often come into eyes unintentionally.

Oh my, you're right. It comes from mar and pit which are two different words combined. A simple name change would be fine I suppose.

[harsh183]

Any update on name change? I was just thinking about it on the other day.

[yhatt]

There is still not specific progress. I think a changed name would become the name for a brand new framework because Marpit architecture is a bit of outdated.