Convert FLAC to MP3 using the CLI

Creating slides in traditional presentation tools can be challenging, especially if you’re working with technical concepts. You’re probably already using Markdown to create other pieces of content, so you know the value it brings to quickly writing and formatting technical content. You can use Markdown to create slide decks, too. While there are tools that display Markdown documents as slides, you’ll need the content in PowerPoint or Google Slides so that others can work with it as well. Pandoc makes this possible.

Pandoc is a command-line tool that converts documents from one format to another. You can use it to create PDFs, HTML pages, Word documents, and even Google Slides.

To explore this, you’ll create a Markdown slide deck about Docker. Then, you’ll use Pandoc to convert that file into PowerPoint slides, which you can import into Google Slides.

What You Need

To complete this tutorial on macOS, you’ll need Homebrew installed, which you can do by following the Install Homebrew tutorial.

Installing Pandoc

You can install Pandoc with your package manager of choice, or by visiting the installation page on the Pandoc web site.

On macOS, you can install Pandoc with Homebrew using the following command:

brew install pandoc

On Ubuntu and Debian systems, install Pandoc with APT:

sudo apt install pandoc

Now that Pandoc is installed, you can create a slide deck.

Building The Markdown Deck

Before creating slides, you need to understand how Pandoc converts Markdown to PowerPoint slides. Here are the key elements:

• Title information uses % at the start of lines.
• Each level 1 heading (#) creates a new slide.
• Code blocks use triple backticks.
• Speaker notes use the ::: notes syntax.
• Notes can contain any valid Markdown.

With that out of the way, create your first deck.

Create a new file called docker-slides.md:

touch docker-slides.md

Start by adding the presentation metadata to the file:

% title: Docker Quick Start
% author: Your Name
% date: November 30, 2024

These three lines create your title slide. The first line is your presentation title, the second is the presenter’s name, and the third is the date.

Now, create the first content slide, which will be about creating Docker containers. Add this content after your title information:

# Creating a Container

Download the `ubuntu:latest` image and create a container:

```bash
$ docker run -it ubuntu:latest
```
::: notes
When you need a new container, this command gets you started.

- Creates and starts a container from the Ubuntu image
- `-i` keeps STDIN open so you can type commands
- `-t` gives you a proper terminal experience
- `ubuntu:latest` gets the newest Ubuntu version
:::

Let’s break down this slide’s structure:

1. # Creating a Container creates a new slide with this title. Top-level Markdown headings create a new slide. You can also use a horizontal rule to specify a new slide.
2. The code block shows the command to run. Note that the code block specifies a language. Pandoc can perform some code highlighting for these code blocks.
3. The ::: notes section contains your speaker notes.
4. You can include Markdown formatting within your notes, including lists and emphasis.

You can also include images, tables, and other Markdown features in your slides.

When creating your Markdown slides, watch out for the following issues:

• Missing blank lines before and after code blocks.
• Using ## instead of # for slides - only level 1 headings create new slides. Use a horizontal rule if you need a new slide that doesn’t have a title.
• Using blockquotes (>) instead of ::: notes syntax for speaker notes.
• Forgetting to close the notes section with :::.

Add the following slides to complete your presentation:

# Connecting to Containers

Connect to a running container and run the `/bin/bash` shell:

```bash
$ docker exec -it container_name /bin/bash
```

::: notes
Need to connect to a running container? This is your command.

- Works on containers that are already running
- Gives you a shell prompt with `/bin/bash`
- Replace container_name with your actual container name
- Great for debugging or running one-off commands
:::

# Mounting Volumes

Make `/host/path` available in your container at `/container/path`:

```bash
$ docker run -v /host/path:/container/path image_name
```

::: notes
Keep your data safe even when containers stop.

- Files in /host/path on your computer show up in /container/path
- Changes in either location sync automatically
- Perfect for development when you're editing files
- Data stays around even if you remove the container
:::

# Port Forwarding

Map port `80` inside the container to `8080` on your machine:

```bash
$ docker run -p 8080:80 nginx
```

::: notes
Make your containerized services available on your computer.

- Maps port 80 inside the container to 8080 on your machine
- Access the service at localhost:8080
- Common when running web servers or APIs
- Change the ports to match your needs
:::

With your Markdown file complete, open your terminal and run:

$ pandoc docker-slides.md -o docker-slides.pptx

This creates docker-slides.pptx with:

• A title slide from your metadata.
• One slide per heading.
• Formatted code blocks.
• Speaker notes ready for presentation mode.

You can open this file in PowerPoint or import it into Google Slides and then continue editing. Here’s the slide deck imported into Google Slides:

This process is excellent for creating a first draft, but you’ll want to keep some things in mind as you iterate:

• Keep commands short - long commands are hard to read on slides
• Use speaker notes for details you’ll explain verbally. Don’t fill up the slides with too much text.
• Include example output when relevant.
• Test the text size in presentation mode before sharing.

This approach works great for creating a quick first draft of slides for any technical topic. You can build on this process, keep your slides in version control, and build a more extensive publication process around them.