| 1 | --- |
| 2 | title: The story of Marp Next |
| 3 | date: 2019-06-06 |
| 4 | description: Today, I'm so excited to introduce the story of Marp Next! The full-rewritten Marp is not only just a writer. To be usable in various situations, we build a brand-new Marp ecosystem consisted of multiple modules. |
| 5 | author: Yuki Hattori |
| 6 | github: yhatt |
| 7 | image: /og-images/the-story-of-marp-next.png |
| 8 | --- |
| 9 | |
| 10 | The first version of [Marp](https://yhatt.github.io/marp/) was released at almost 3 years ago. At first, it was started from a simple tool for personal usage called "mdSlide". And now, Marp has been used by a lot of users who would recognize the real value of the presentation writer. Marp is amassed around [8,000 stars](https://github.com/yhatt/marp/stargazers) until now. |
| 11 | |
| 12 | However, our headache brought from lacked maintainability to develop. We had received so many requests to the old Marp app, and it has to evolve to keep providing the best writing environment of presentation deck. |
| 13 | |
| 14 | Today, I'm so excited to introduce the story of Marp Next! The full-rewritten Marp is not only just a writer. To be usable in various situations, we build **a brand-new Marp ecosystem** consisted of multiple modules. They are developed with JavaScript and TypeScript, and much more maintainable than the previous Marp. |
| 15 | |
| 16 | <!-- more --> |
| 17 | |
| 18 | # Marp ecosystem |
| 19 | |
| 20 | Marp Next has two core components: **[Marpit]** framework and **[Marp Core]**. Tools by Marp ecosystem are usually based on these. |
| 21 | |
| 22 | ## Marpit |
| 23 | |
| 24 | **[Marpit]** is _the skinny framework_ for creating HTML slide deck from Markdown. It is designed to convert Markdown into only minimum assets consisted of static HTML and CSS, and the output can convert into PDF slide deck by printing through Chrome / Chromium. |
| 25 | |
| 26 | Marpit has created for using as the base of Marp ecosystem, but it is also independent framework. You may integrate Marpit's Markdown conversion with your tool, even if it's not Marp: [reveal.js](https://codesandbox.io/embed/nw80vrxvpp), [WebSlides](https://codesandbox.io/embed/j3wo2091yw), and so on. |
| 27 | |
| 28 | [marpit]: https://marpit.marp.app/ |
| 29 | |
| 30 | ### [Marpit Markdown]: Keep compatibility with a plain Markdown document |
| 31 | |
| 32 | We had received [many requests][issues] to the old Marp, about the additional syntax to help creating beautiful slide deck. On the other hand, we also have received a request that [must respect Markdown syntax strictly](https://github.com/yhatt/marp/issues/87). We have to deal with these contradicted issues. |
| 33 | |
| 34 | Additional syntax provided by Marpit should never break [CommonMark](https://commonmark.org/) document. Thus, the result of rendering keeps looking nice even if you open the Marpit Markdown in a general Markdown editor. And you can even extend the additional syntax via [markdown-it plugins](https://marpit.marp.app/usage?id=extend-marpit-by-plugins) if you need. |
| 35 | |
| 36 | [marpit markdown]: https://marpit.marp.app/markdown |
| 37 | [issues]: https://github.com/yhatt/marp/issues |
| 38 | |
| 39 | ### [Theme CSS]: Design your deck with clean markup |
| 40 | |
| 41 | Marpit has the theming system to allow designing everything of slides by CSS. |
| 42 | |
| 43 | The old Marp had the _limited_ theming system and required deep diving to internal for customization: Build system, [Sass], the logic of Marp app, and so on. So we had to create a brand-new theming system for easy customization of theme with only general CSS knowledge. |
| 44 | |
| 45 | Marpit's it only requires a pure CSS, and no additional knowledges! You have only to focus styling HTML semantic elements. It means that you can create theme CSS from now! |
| 46 | |
| 47 | In addition, Marpit has the pixel-perfect slide system like PowerPoint and Keynote. Theme creator never needs to worry about the responsive layout, and could provide design exactly as the author wanted with less effort. |
| 48 | |
| 49 | [theme css]: https://marpit.marp.app/theme-css |
| 50 | [sass]: https://sass-lang.com/ |
| 51 | |
| 52 | ### [Inline SVG slide] (Experimental) |
| 53 | |
| 54 | Our unique idea is wrapping each slides by inline SVG. It might feel a bit strange, but makes many advantages. |
| 55 | |
| 56 | - Supports pixel-perfect scaling via style definition and **realizes Zero-JS slide deck**. |
| 57 | - Isolates Markdown contents and prevents that injected DOM by Marpit's advanced feature breaks design defined in theme CSS. |
| 58 | |
| 59 | Thanks to the power of SVG, we can keep a framework simple and maintainable. [Marp Core] is based on inline SVG slide by default. |
| 60 | |
| 61 | [inline svg slide]: https://marpit.marp.app/inline-svg |
| 62 | |
| 63 | ## Marp Core |
| 64 | |
| 65 | **[Marp Core]** is a base converter for our projects extended from Marpit. In short, it is a battery-included Marpit. |
| 66 | |
| 67 | Marpit only has bare essential features, so it might have not enough to start writing your deck. Marp Core provides the practical syntax, additional features, and built-in themes. |
| 68 | |
| 69 | Many of the features are based on the old desktop app, and have improved to be suitable to Marpit. Of course, we added the new features for creating more beautiful deck. |
| 70 | |
| 71 | [marp core]: https://github.com/marp-team/marp-core |
| 72 | |
| 73 | - Built-in themes (Default, Gaia, and _new_ Uncover theme) |
| 74 | - Included Emoji support 😁 |
| 75 | - [KaTeX](https://katex.org/) Math typesetting |
| 76 | - `size` global directive |
| 77 | - Auto scaling features (_new_) |
| 78 | - Fitting header via `<!-- fit -->` annotation |
| 79 | - Scale-down overflowed fence, code, and math block |
| 80 | |
| 81 | # Applications |
| 82 | |
| 83 | ## Marp CLI |
| 84 | |
| 85 | [marp cli]: https://github.com/marp-team/marp-cli |
| 86 | |
| 87 | **[Marp CLI]** is a CLI interface of Marpit and Marp Core converter. It's a Swiss-Army knife for Marp slide deck! |
| 88 | |
| 89 | [][marp cli] |
| 90 | |
| 91 | You can use it right now by running `npx @marp-team/marp-cli` if [Node.js](https://nodejs.org/) is installed. |
| 92 | |
| 93 | - Export to HTML, PDF, and image |
| 94 | - Watch the change of your Markdown and theme (`--watch`) |
| 95 | - Open preview window for presentation (`--preview`) |
| 96 | - Full-customizable engine based on Marpit framework |
| 97 | |
| 98 | Marp had a text editor originally, but you might think that want to write the slide deck with your favorite editor. If you use Vim, you would feel uncomfortable not to be usable Vim style key-binding. From now on, use Marp CLI's watch mode together with original Vim! |
| 99 | |
| 100 | And Marp CLI can create really practicable static HTML as like as a presentation mode! It is powered by deep integration with [Bespoke.js](https://github.com/bespokejs/bespoke). |
| 101 | |
| 102 | Thanks to [Netlify], [Now], and more hosting services, Marp CLI also brings a efficient Git management for creating slide deck just like [GitPitch]. I've created [an example slide](https://yhatt-marp-cli-example.netlify.com/) managed via [GitHub repository](https://github.com/yhatt/marp-cli-example) as a good starter to help writing your slide deck. Try to use it via "Deploy to Netlify" button on [README](https://github.com/yhatt/marp-cli-example/blob/master/README.md#usage)! |
| 103 | |
| 104 | [netlify]: https://www.netlify.com/ |
| 105 | [now]: https://zeit.co/now/ |
| 106 | [gitpitch]: https://gitpitch.com/ |
| 107 | |
| 108 | ## Marp Web (_tech demo_) |
| 109 | |
| 110 | **[Marp Web]** is a Web interface of Marp presentation writer. It allows writing your slide deck as like as a traditional desktop app. |
| 111 | |
| 112 | > The current Marp Web is just a tech demo. We are planning to re-implement Marp Web based on well-known framework (like React) for building SPA. |
| 113 | |
| 114 | [marp web]: https://web.marp.app/ |
| 115 | |
| 116 | ### Progressive Web Apps |
| 117 | |
| 118 | It made [some strong oppositions by users that is using Marp in offline](https://github.com/yhatt/marp/issues/174#issuecomment-294594856) when an idea of migration to web-based app is proposed for keeping maintainability of Marp. It was caused that a thinking of PWA was not general at that time. |
| 119 | |
| 120 | And 2 years later, the time has come to use PWA! After the first access to **[https://web.marp.app/][marp web]**, Marp Web would be ready to use in both of online and offline. Online resources to use the web interface would be cached in your browser, and use them when network is offline. |
| 121 | |
| 122 | [][marp web] |
| 123 | |
| 124 | ### Use via any devices |
| 125 | |
| 126 | By migrating to the web-based app, Marp will be able using in mobile device: Android and iOS. That's sure it's well suited to the tablet device like iPad. |
| 127 | |
| 128 |  |
| 129 | |
| 130 | Marp Web would work also in Chrome OS well. Marp especially has many users in the field of education, and supporting Chrome OS that has large share in its field is meaningful. |
| 131 | |
| 132 | ### Blazing-fast live preview ⚡️ |
| 133 | |
| 134 | We think Marp's important feature is a blazing-fast live preview. In the web-based app, realizing the same feature had many difficulties. |
| 135 | |
| 136 | In currently published tech-demo, you can try Marp's really fast preview on the web. The preview applies as soon as typing, and it would not block your typing even if you have a large Markdown slides over than 100 pages. |
| 137 | |
| 138 | # Integrations |
| 139 | |
| 140 | The modularized Marp Core brought Marp integrations for some tools. |
| 141 | |
| 142 | ## [Marp for VS Code][marp vscode] |
| 143 | |
| 144 | Honestly, I don't think to want to make a new editor because there are many great Markdown editors in the world. I had been thinking it would be awesome if Marp could integrate with a something else powerful Markdown editor. And now, Marp can use in [Visual Studio Code](https://code.visualstudio.com/)! |
| 145 | |
| 146 |  |
| 147 | |
| 148 | It was realized because VS Code is using the same Markdown engine (markdown-it) as Marpit framework. Of course, you can export slides as PDF and HTML easily, powered by [Marp CLI]. |
| 149 | |
| 150 | [marp vscode]: https://marketplace.visualstudio.com/items?itemName=marp-team.marp-vscode |
| 151 | |
| 152 | ## [Marp React] & [Marp Vue] (In development) |
| 153 | |
| 154 | [marp react]: https://github.com/marp-team/marp-react |
| 155 | [marp vue]: https://github.com/marp-team/marp-vue |
| 156 | |
| 157 | Marp's blazing fast live-preview is not only for ours! We provide Marp renderer component into [React][marp react] and [Vue][marp vue]. Both Marp React and Marp Vue have supported the incremental update using framework's virtual DOM, and they are been easy to build your app. |
| 158 | |
| 159 | Especially, Marp React would become to the base of the future of [Marp Web]. |
| 160 | |
| 161 | # Migration plan |
| 162 | |
| 163 | ## Desktop app ([yhatt/marp](https://github.com/yhatt/marp)) |
| 164 | |
| 165 | If you are using an old Marp application, **you should migrate to use Marp Next tools.** I NEVER recommend continue to use the old Marp, because _its maintainance has stopped 2 years ago and there is concern about security issues._ |
| 166 | |
| 167 | In future, the main interface would become to Marp Web. We have bet to PWA technology that has a lot of advantages. The desktop app is planned as "Marp Desktop" but it just may become a wrapper of Web interface. |
| 168 | |
| 169 | I would stop publishing the old Marp and archive its repository if Marp Web has grown to become replaceable the old Marp. |
| 170 | |
| 171 | ## Your slide deck |
| 172 | |
| 173 | Your Markdown slides written in the old Marp syntax should rewrite to suit to the brand-new Marp ecosystem. |
| 174 | |
| 175 | In a new Marp, we have reconsidered Markdown syntax based on feedback to the old Marp app. So, some syntaxes are losing compatibility. |
| 176 | |
| 177 | ### Syntax |
| 178 | |
| 179 | - In Marp Core, non-whitelisted HTML elements are disabled by default because of security reason. Currently our whitelist includes only `<br>` element. Some Marp Next tools has provided preference to enable HTML, but you should take care for enabling HTML in untrusted Markdown. |
| 180 | |
| 181 | ### Directives |
| 182 | |
| 183 | - Directives would be parsed by YAML parser tuned for Marp (Marpit). Thus spot directive prefix `*` is changed to `_` for keeping YAML syntax. |
| 184 | - `$` prefix no longer required to global directives. |
| 185 | - Slide size still can choose from "16:9" and "4:3", through `size` global directive (provided by Marp Core). If you want to use custom size or you're using Marpit framework, please use [theme CSS](https://marpit.marp.app/theme-css?id=slide-size). |
| 186 | - `page_number` directive is renamed to `paginate`. |
| 187 | - `template` directive is renewed to use `class` directive. It can define HTML class per slides. |
| 188 | - `prerender` directive is removed. It brings user confusing about exported PDF quality. |
| 189 | |
| 190 | ### Image |
| 191 | |
| 192 | - Background image `![bg]()` has no filter applied by default. Try using `![bg opacity]()` if you want. |
| 193 | - The inline image is no longer scalable by percentage `![50%]()`. (It's not supported in Firefox) Instead you can use `width` (`w`) and `height` (`w`) keyword to resize image as like as `![width:300px]()`. |
| 194 | - `![center]()` won't work. It requires changing image to the block element and brings confusion to theme author. You can tweak style if you still want. |
| 195 | |
| 196 | ```html |
| 197 | <style> |
| 198 | img[alt~='center'] { |
| 199 | display: block; |
| 200 | margin-left: auto; |
| 201 | margin-right: auto; |
| 202 | } |
| 203 | </style> |
| 204 | ``` |
| 205 | |
| 206 | # Try Marp Next! |
| 207 | |
| 208 | Marp Next just focuses to build the ecosystem for Markdown slide deck with pure open source. We expect to expand Marp productivity together with open source community. |
| 209 | |
| 210 | We still have stood at the beginning of the brand-new ecosystem. Are you interested to Marp team and our ecosystem? We welcome to start your contribution! See [our contributing guideline](https://github.com/marp-team/.github/blob/master/CONTRIBUTING.md) and get started! |
| 211 | |
| 212 | > PS. [GitHub Sponsors](https://github.com/sponsors/yhatt) is also good contribution if you want to help my working for open source. |
| 213 |