This repository is a template repository that allows you to create slides utilizing Marp to its fullest potential, with ease.
- 🚀 Automatic deployment to GitHubPages via GitHubActions
- 🖼️ Support for setting OGP images for the title slide
- 🚄 Lightweight slide creation using Markdown extended syntax
- 🎨 Diverse slide expressions with CSS utility classes
- 🔧 A script to easily create new slides from the template
For demo slides using this repository, please refer to GitHubPages.
Build your own original slide environment using Markdown extended syntax and CSS utility classes!
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
| 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.
- Create a repository by following the instructions in Creating a repository from a template.
- Change the repository settings according to the documentation to enable deployment from GitHubActions to GitHubPages.
- Once the GitHub setup is complete, download the repository locally using $ git clone.
- Change various settings such as URLs within the repository to match your ID and repository name.
- A dedicated script is provided for easy modification.
$ scripts/init- Follow the displayed instructions and enter your GitHub user ID and repository name.
- Once entered, the script will automatically modify the settings.
- Change the language and timezone settings as needed.
- The language setting is defined in .marprc.yml, and the timezone setting is specified in .github/workflows/deploy.yml.
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.
Install the dependencies to enable markdown-it plugins and Marp CLI.
$ pnpm install- Create slides in the
srcdirectory. - A command is provided to easily create new slides from the template.
# 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!
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:tmpWarning
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! 🎉
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:
- Customizing the design and defining utility classes with CSS files in the themes directory
- Extending Markdown syntax using various plugins of markdown-it
Detailed usage for each is described below.
- Theme definitions are written in themes/index.css.
- For example, edit this file if you want to change Marp's default theme or modify the syntax highlighting style (enabled by the integration of
markdown-it-prism). - Additional custom themes that affect the entire slide are written in themes/global.css.
- Edit this file to create your own unique theme!
- Convenient utility classes for slides are defined in themes/utility.css.
- For example, classes are added to change text sizes or to support element display in columns.
- A few useful CSS classes are provided by default, but feel free to customize them to suit your preferences!
Tip
The design of utility classes is inspired by Tailwind CSS.
Markdown extension settings are written in engine.mjs.
Recommended markdown-it plugins have been integrated.
markdown-it-containermarkdown-it-attrsmarkdown-it-markmarkdown-it-insmarkdown-it-prismmarkdown-it-textual-uml
Please refer to the official documentation for each plugin.
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.
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}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.
:::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.
:::_
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 :.
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.
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.
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.
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! ✨