The conference you signed up for is in two weeks, but you haven't started with the slides yet. Focusing on the content should be your priority, so you start putting together an outline with Google Slides. Nevertheless, you quickly realize that formatting the presentation will take forever: choosing the font and background that fits, aligning all the images... why the spacing between elements is always inconsistent between slides?

I faced this situation when preparing the slides for my presentation on Docs-As-Code for PyCon APAC 2020. The clock was ticking, so I ended writing the slides in plain text instead while looking for an alternative to turning these annotations into visually appealing slides.

The tool I ended up choosing is called Marp. At first, I was skeptical if Marp would offer the flexibility required to design slides using Markdown, but now I'm delighted with the result considering the time spent. Here is what I learned.

Organizing the presentation

No matter which tool we use to create our presentation, we still need to have clear its content 😅. Open a new file with the extension .md. Then, write your notes for your presentation in plain text using Markdown syntax to describe how to format text.

New to Markdown? Here is a cheat sheet with the most common annotations you will need to format titles, links, and tables.

Once you have all the content outlined, split the slides with the annotation ---. Here is an example.

# Slide 1 * Item 1 * item 2 * Item 3 --- # Slide 2 ## Subtitle Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Creating slides with Marp

Marp is the framework we'll use to turn Markdown into a beautiful slide deck. At this point, the tool is not available as a web application; a bit of experience playing with the terminal is required to use the tool.

For example, try to run one of the following commands to convert a Markdown slide deck into HTML, PDF, or PTTX. Replace with your file name.

# Convert slide deck into HTML npx @marp-team/marp-cli --html # Convert slide deck into PDF npx @marp-team/marp-cli --pdf # Convert slide deck into PowerPoint document (PPTX) npx @marp-team/marp-cli --pptx

Do you want to preview the slides while you edit the contents? Run the next command instead to run Marp in watch mode. Then, open the resulting HTML file with your preferred browser.

npx @marp-team/marp-cli -w

If you use Visual Studio Code, you can preview the resulting slides as you write them with the Marp Extension for VSCode.

Adding a theme

Let's change the style of the presentation. You can use one of the built-in themes. At the top of the Markdown file, define which theme you want to apply using the directive theme. The file header should look like:

--- theme: default ---

For my presentation, I have decided to go with the theme gaia. Marp provides other configurable directives that apply to all the slides simultaneously. For example, I also changed the font color, the background and enabled pagination for my presentation.

--- theme: gaia color: #000 colorSecondary: #333 backgroundColor: #fff backgroundImage: url('') paginate: true ---

Styling a single slide

In some situations, we only want to enable a directive for a given slide. We can apply directives selectively with comments. The next code snippet shows how to disable pagination for the first slide.

<!-- _paginate: false --> # Slide 1 * Item 1 * item 2 * Item 3 ---

Another common directive used per slide is _class. Each theme may come with a set of classes predefined. For example, the theme gaia introduces the class lead. When used, this centers the slide contents.

Using classes with Marp

As you can see, the first slide used the class centering the title, whereas the second slide didn't, and the contents appear aligned on top.

If you are a skilled CSS developer, you might want to create a custom theme from scratch. John Wadleigh explains how to do it in this guide.

Working with images

A picture speaks 1,000 words. Most presentations include images, and Marp extends Markdown to make sure these are adequately sized.

Try to add an image to your slides, and change the size with the options width and height.

![w:32 h:32](image.jpg)

You can also apply filters to images, such as adding opacity, a shadow, or even rotate the image. Here you have all the available predefined CSS filters supported. For example, the next snippet shows how to convert a photo to grayscale mode.


Marp also brings the option to use images as backgrounds. Backgrounds also accept the same filters as images and additional options to position them.

By default, all background images fit the slide, but you can use the option auto to preserve the original size.

# The image fits the slide ![bg](image.jpg) # The image is not rescaled ![bg auto](image.jpg) # The image is scaled in a percentual value ![bg 80%](image.jpg)

The options left or right make space for the specified size background.

Background left option

Final thoughts

Writing all the slides in Markdown has been fun! I felt much more efficient in creating the presentation. The outcome was pretty decent compared to other slide decks I made before using other WYSWYG tools.

On the other hand, it might not work for every presentation because mastering Marp has a learning curve. Indeed, I would not feel comfortable with the tool if I had to compose a very intricate design.