marp-web

Language: 🇺🇸 🇯🇵

Deploy

Awesome Marp Template

This repository is a template repository that allows you to create slides utilizing Marp to its fullest potential, with ease.

🚀 Features

For demo slides using this repository, please refer to GitHubPages.
Build your own original slide environment using Markdown extended syntax and CSS utility classes!

📂 Directory Structure

The contents of the main directories and files are as follows.
Feel free to customize them to suit your preferences!

.
├── .marprc.yml     # Marp CLI configuration file
├── engine.mjs      # Marp CLI engine extension
├── scripts/
│   ├── check       # Script to check if the OGP URLs for the slides are correct
│   ├── init        # Script for repository setup
|   └── new         # Script to create new slides from the template
├── src/            # Slide directory for deployment
│    └── demo/      # Demo slide directory
├── template/       # Template slide directory
└── themes
    ├── global.css  # Custom theme affecting the entire slide
    ├── index.css   # Entry point for the custom theme
    └── utility.css # Various utility classes used in the slides

✅ Requirements

Tools version
Node.js 20.18.0
pnpm 9.15.1

[!tip] It is recommended to install Node.js using a version manager such as nodenv.

🎉 Getting Started

0. Create a repository from the template

  1. Create a repository by following the instructions in Creating a repository from a template.
  2. Change the repository settings according to the documentation to enable deployment from GitHubActions to GitHubPages.
  3. Once the GitHub setup is complete, download the repository locally using $ git clone.

1. Repository Setup

$ scripts/init

[!warning] The script uses the sed command.
It works fine on Mac (BSD), but on Linux (GNU), the option syntax differs, which may cause errors.
Linux (GNU) users should modify the sed command in the script as needed.

2. Install Dependencies

Install the dependencies to enable markdown-it plugins and Marp CLI.

$ pnpm install

3. Create a New Slide

# Create a New Slide
$ pnpm new <slidename>
# If you want to group them, you can also split and create directories under src.
$ pnpm new path/to/<slidename>

The template slides to copy are located in the template directory.
Feel free to customize them to suit your preferences!

4. Edit and Preview the Slide

Slides can be previewed in real-time in the browser using the features of Marp CLI.

# When editing slides under the src directory
$ pnpm dev
# When editing template slides
$ pnpm dev:tmp

[!warning] This repository is extended using the Engine feature of Marp CLI.
As a result, some features of the VSCode extension marp-vscode are not available.
For more details, refer to @marp-team/marp-vscode/issues/85#issuecomment-543798586.

That’s it for the basic usage! 🎉

🙌 Enjoy Marp even more! 🙌

Marp allows you to customize slide designs using the features of Marpit.
Additionally, you can extend the Markdown syntax using the Engine feature of Marp CLI.

In this repository, customization is mainly done in the following two ways:

Detailed usage for each is described below.

Customizing the Theme

[!tip] The design of utility classes is inspired by Tailwind CSS.

Using Markdown Extended Syntax

Markdown extension settings are written in engine.mjs.
Recommended markdown-it plugins have been integrated.

Please refer to the official documentation for each plugin.

✨The Ultimate Marp Slide Creation Technique ✨

Finally, let me introduce the ultimate combination of Markdown extended syntax and custom themes, which is the essence of this repository 💪
You can check the actual display in the demo slides.

Assigning CSS Classes with {.class}

By using the markdown-it-attrs plugin, you can assign CSS classes to specific elements.

This is a paragraph.{.gray}

This input will be converted to the following HTML.

<p class="gray">This is a paragraph.</p>

The .gray class is a class defined in themes/utility.css that changes the text color to gray.
This allows you to easily apply styles to specific elements within the slide.
It is also possible to specify multiple classes at the same time, as shown below.

This is a small and gray paragraph.{.text-sm .gray}

Decorating Specific Strings with == and {.class}

By combining markdown-it-mark and markdown-it-attrs, you can decorate specific strings only.

This is a ==red=={.red} text.

This input will be converted to the following HTML.

<p>This is a <mark class="red">red</mark> text.</p>

With markdown-it-mark, you can wrap specific strings with == to convert them into inline <mark> elements, and by applying a class to them, you can easily decorate only those specific strings.

Change the style for each block with markdown-it-container.

By enclosing with :::, you can change the style for each block.
In this repository, :::c and :::_ are predefined.

Display in columns with :::c

:::c
Column 1

Column 2

Column 3
:::

This input will be converted to the following HTML.

<div class="c">
  <p>Column 1</p>
  <p>Column 2</p>
  <p>Column 3</p>
</div>

The .c class is defined in themes/utility.css as the flex-container setting. This allows you to easily display elements in a column layout within the slide.

Use :::_ for grouping.

:::_
Group 1

Group 2

Group 3
:::

This input will be converted to the following HTML.

<div class="_">
  <p>Group 1</p>
  <p>Group 2</p>
  <p>Group 3</p>
</div>

The ._ class is an undefined dummy class.
A specific use case is when you want to apply a style to multiple elements at once, or when you want to group elements without changing their styles.

:::_ {.blue}
This is a blue text.

This is a blue text.

This is a blue text.
:::

::::c
:::_
## Left column
This is a left column text.
:::
:::_
## Right column
This is a right column text.
:::
::::

When nesting as shown above, you distinguish them by increasing the number of :.

Display a filename in a code block with {name=filename}

This repository provides a feature that allows you to easily display a filename in a code block.
By adding {name=filename} after the code block, you can display the filename.

```js {name=index.js}
const message = "Thank you for using Awesome Marp Template!";
console.log(message);
```

The display will be as follows.

Display a filename in a code block

For the implementation details of this utility, please refer to themes/utility.css.

[!warning] The implementation method may vary depending on the theme used by Marp.
If you are changing from the initial gaia theme in this repository, modifications are required.
Specifically, implementing it with the default theme can be quite challenging.
If you want to use this feature, it is recommended to either invent your own implementation method or select the gaia or uncover theme.

Use Alert Design

This repository provides a feature to easily apply alert designs.
By using the classes .note, .important, .tip, .warning, and .caution, you can apply alert designs.

Alert Design

That concludes the explanation of this repository!
Feel free to use this template as a reference and enjoy creating slides that make the most out of Marp! ✨

This site is open source. Improve this page.