Proposal: should Marp's Markdown dialect have a name?

[maagenta]

The observation

Marp is described as a "Markdown Presentation Ecosystem," and almost every part of that ecosystem has a clear, searchable name: Marpit (the framework), Marp Core (the converter), Marp CLI, and Marp for VS Code. Each one is a noun you can install, link to, and talk about.

There's exactly one thing that doesn't have a name: the syntax you actually write.

When we need to refer to it, we fall back on descriptions: "Markdown with Marp directives," "Marp-flavored Markdown," or just "Markdown, but with the slide stuff." Every one of those is a description, not a name. You can't npm install it, you can't title a doc page with it, and you can't say it out loud in one word.

Why it probably ended up nameless

This isn't an oversight so much as a side effect of how the project grew. Marpit was conceived as a framework first: its job is to turn Markdown into slide HTML + CSS. From that point of view the input was never "a language," it was just "the Markdown that Marpit happens to eat." So the engine got a name and the language it defines never did. Reasonable at the time; a little awkward now.

Why a missing name is a real problem

A nameless language quietly taxes everything around it:

• Documentation. Every sentence that should introduce the syntax has to describe it instead. That makes the docs wordier and vaguer than they need to be.
• Teaching and onboarding. Newcomers have no single term to anchor on. "Learn Markdown, then also learn the Marp parts" is two concepts where it could be one.
• Discoverability. People search for names. A named dialect is something you can blog about, tag, and find.
• Conversation. "Is this valid Marp syntax?" is ambiguous (the syntax? the CLI? the theme?). A name removes the ambiguity.

Prior art: small languages that do have a name

This exact pattern, a focused language built on top of or by combining existing ones, is everywhere. The successful ones almost always have a name, and that name is precisely what lets their documentation open with one confident sentence:

• MDX = Markdown + JSX. Its docs introduce it in a single line: a format for writing JSX inside Markdown. One word, instant mental model.
• GitHub Flavored Markdown (GFM) = CommonMark + a few extensions (tables, task lists, strikethrough, autolinks). A named dialect of Markdown, which is exactly Marp's situation.
• Sass / SCSS = a superset of CSS. "Sass is a CSS extension language." Naming it is a big part of what made it teachable.
• Mermaid = a text syntax for diagrams. The name is the thing you search for, install, and discuss.

Look at the shape of every one of those intro sentences:

<Name> is a <kind of thing> that <does X>.

You literally cannot write that sentence without a name. Right now the Marp docs can write it about Marpit-the-framework, about the CLI, about Marp Core, but not about the syntax itself, because the syntax has no subject to put at the front.

The proposal

Give the language a name. The most natural candidate is Marpit, the framework that already defines the syntax.

Reusing the framework's name for its language is not a conflict; it's the norm:

• "Markdown" names both the language and (originally) John Gruber's reference implementation.
• "Sass" names the language; Dart Sass is just one implementation of it.

So Marpit-the-framework defining Marpit-the-language is clean and intuitive, not confusing. The framework is simply "the reference implementation of Marpit."

And with a name in hand, the documentation finally gets a real opening line:

Marpit is a language that combines Markdown with CSS and a small set of special definitions to make Markdown useful for presentations.

Compare that to the current alternative:

"Marp lets you write presentations in Markdown with some extra directives and theming."

The first is a definition. The second is an apology. The whole rest of the docs reads better when it can build on the first one.

If "Marpit" feels too overloaded

If reusing the framework's name is uncomfortable, a few alternatives keep the same spirit:

• Marpdown: Marp + Markdown; self-explanatory the instant you read it.
• Marp Markdown: a named dialect, GFM-style ("GitHub Flavored Markdown" -> "Marp Flavored Markdown").
• MarpMD: short, fits package/tooling naming.

Open questions for discussion

• Is overloading Marpit (framework and language) a helpful simplification or a source of confusion?
• Which layer are we naming? The base syntax (directives, slide separators, CSS theming) is defined by Marpit, but the fuller writing experience (math via KaTeX, emoji, image/background syntax, auto-scaling) comes from Marp Core. Does the name belong to the base syntax, the extended syntax, or both?
• Would a name change anything user-facing, or is this purely a documentation and communication convention?

If folks are open to it, the cheapest first step is just adopting the name in the docs: start a page with "Marpit is a language that…" and see how much clearer everything downstream reads.

[yhatt]

When the Markdown syntax adopted by Marp needs to be referred to, we currently call it "Marp Markdown". Similarly, when describing the Marpit syntax, we call it "Marpit Markdown". At this moment, we do not see significant benefits in redefining these names, so we are not actively pursuing that.

While giving the syntax a unique name sounds reasonable, there is a clear reason why we have not officially named it yet.

• Unique names tend to give beginners the negative impression, "I have to learn a new conceptual language". Since its inception, Marp has been designed with compatibility with CommonMark and general Markdown flavors as a top priority, and no special syntax is essentially required just to create slides. To lower the barrier for users, it is necessary to convey the impression that one can use Marp with only existing Markdown knowledge; adopting a name for a unique flavor would be disadvantageous in that regard.
• Marp allows syntax to be extended via plugins. If syntax added by users is mistaken for part of the Markdown syntax adopted by Marp, it could lead to confusion regarding the scope of the syntax referred to by the name.

All that general consumers really need to know is "Marp". Marpit is the internal implementation of Marp and a framework for developers to create slide syntaxes. We originally want to avoid burdening general users with these technical details as much as possible, so we think it does not need to make the syntax of Marpit stand out by naming.

[maagenta]

Got it, so the syntax is technically called Marpit Markdown, and Marp Markdown once the extensions are included. That makes sense, thanks!

That said, I think having both "Marpit" and "Marp" makes things a little less consistent. As far as I can tell, the official syntax documentation refers to Marpit (here), but Marp doesn't seem to have any documentation on the website — instead it lives in the GitHub repository (here), which makes it harder to follow. Personally, I think Marp should have its own documentation page in the same format as the Marpit docs.

I also don't quite understand the decision to separate Marpit from Marp Core. I'd imagine the extensions could be enabled by importing a class from the library or by using a flag in the Markdown file. Another option might be to keep the "Marpit" name across the board e.g., MarpitCore, MarpitExtended, and Marp (the tool that actually uses the syntax).

I'm raising all this because I really love the idea and the syntax of Marpit, and I think the syntax should be able to transcend the tool. Ideally it could become a standard one day and be adopted by other tools, the way Mermaid has been but that requires very well-defined documentation and a high level of consistency.

On a personal note, I'm thinking about building a tool down the line that converts Marp Markdown (MarpitExtended Markdown, haha) to PPTX in Python using the library python-pptx . I'll try to PR the project, but I suspect you might not be keen on it since it's written in a different language. In that case, I could build it as a standalone tool and describe it as something like "A tool to convert Marp Markdown to PPTX." Either way, clear and consistent documentation updates in the official webpage would be really helpful instead of having it spread between the webpage and the github repos so I can keep my own tool in sync with new features.

Finally, I think the Documentation link belongs in the website header, documentation is really important. I know it's currently under the Marpit framework section, but given how important it is, it deserves a spot in the header. Look at the official ffmpeg or Mermaid sites, for example: both put the Documentation link right in the header. At this point, that's almost a standard.

PS: If you need help making the documentation I am happy to help

Thanks!

[yhatt]

It's related to #126, #503, and #505. Especially, in #505, I've already described about the new documentation on https://marp.app and why we do not place a link to https://marpit.marp.app on the header. Please track these discussion threads if interested. Although I'm usually busy with business, I'd like to resume it as soon as I have a good block of time.

Marpit and Marp Core have different scopes: Marpit is a minimal framework for building slide engines, and Marp Core is a curated engine that provides the official Marp authoring experience. This separation is intentional: features that are useful for Marp are not always appropriate for every Marpit-based engine.

For instance, Marp Core comes with built-in support for things like math typesetting, syntax highlighting, emojis, and auto-scaling. These features in a single package @marp-team/marp-core are great for providing a consistent experience right out of the box, but they also bring in extra dependencies and certain design choices that might not suit everyone. By keeping these out of the Marpit itself, we ensure that users aren't forced to deal with extra weight or features they don't need, and also Marpit can stay lightweight, predictable, and easy to build upon.