mdp - A command-line based markdown presentation tool

mdp: A Command-Line Markdown Presentation Tool

mdp is a compact, command-line driven tool designed to turn Markdown into a sequence of presentation slides. Built around ncurses, it runs inside a terminal and lets you navigate through slides with a familiar keyboard interface. The project emphasizes simplicity and portability, delivering a straightforward workflow for creating and delivering slide decks directly from text-based Markdown sources. The output is not a heavy GUI application; instead, it renders slides in the terminal, with color and formatting features that leverage terminal capabilities.

What mdp does and why you might want it

• A lightweight presentation engine: mdp reads a Markdown file and renders it as a slide deck inside your terminal. It relies on simple rules to split slides and to apply formatting, making it ideal for quick, distraction-free talks.
• Terminal-first experience: everything runs in the command line. If you spend most of your day in a shell, mdp keeps your workflow cohesive without requiring a separate GUI tool.
• Focus on readability and speed: the tool emphasizes fast slide creation from plain text. You can iterate rapidly, tweak content, and present with minimal setup.
• Extensible through configuration: there is a dedicated configuration hook that lets you tune colors, keybindings, and list types to suit your preferences. While color customization is supported, it works best in environments that support eight colors.

Getting started with mdp

mdp relies on ncurses, so you’ll need the appropriate development headers to compile it. The setup varies by platform, but the goal remains the same: ensure the ncurses libraries and headers are available, then build and install.

Prerequisites and platform notes

• Raspbian (Raspberry Pi): install libncurses5-dev and libncursesw5-dev to provide the needed headers and libraries.
• Fedora: install ncurses-devel and ncurses-c++-libs to compile and link properly.
• Arch Linux: mdp can be installed from the existing package repository.
• Cygwin: there is an available package you can install from the setup program.
• Debian/Ubuntu: either use the MD package from the distribution or run apt-get install mdp.
• FreeBSD: the misc/mdp port provides the necessary support.
• macOS: you can install via Homebrew (brew install mdp) or via MacPorts.
• Slackware: SlackBuilds are available, or you can use sbopkg to retrieve and build mdp.
• General tip: ensure TERM is set up correctly for color features. For full color fading effects, you’ll typically want TERM to be xterm-256color.

How to install mdp

The typical workflow is straightforward. You clone the repository, build, and install, then you’re ready to begin with a sample Markdown file.

• Clone the repository:
• git clone https://github.com/visit1985/mdp.git
• Change into the directory:
• cd mdp
• Compile:
• make
• Install:
• make install
• Run a quick test with a sample file:
• mdp sample.md

If you’re on a distribution with an available package, you can often skip the build steps and install mdp directly from the package manager.

• Arch Linux users can leverage the existing package.
• Ubuntu/Debian users can install via the DEB package or apt-get install mdp.

How to use mdp: slide structure and formatting

mdp maps Markdown features into a presentation-friendly format. The basic ideas are simple to grasp, and the project documents a few conventions that help you craft slides with minimal friction.

Slide separation and structure

• Horizontal rulers (usually a line of dashes or similar) act as slide separators. Each segment between separators becomes an individual slide.
• The interface supports standard Markdown features for content:
• line-wide markup (full-width rules or emphasis)
• headlines (via Markdown syntax)
• code blocks and inline code
• quotes
• unordered lists
• inline formatting such as bold and code
• A distinctive feature is the use of headers prefixed by the @ symbol. These special headers define the slide title and author information, and they influence the display in the top and bottom bars of the slide.

Title and author display

• The first two header lines in the Markdown file are displayed in the top and bottom bars of the viewer. This provides a concise framing for the presentation: the slide’s title appears at the top, and the author information is shown along the bottom bar.

Working with sample.md

• The sample Markdown file demonstrates how the layout is rendered, how headers integrate into the frame, and how content flows across slides. As you craft your own markdown, you can test changes by reloading the input and stepping through slides to verify the visuals and navigation behavior.

Default controls: moving through slides and managing the session

mdp includes a practical set of keyboard controls that make slide navigation quick and intuitive. The default bindings are designed to be familiar to users who have navigated other text-based or keyboard-driven tools.

• Basic navigation:
• h, j, k, l (and arrow keys)
• Space and Enter
• Backspace
• Page Up and Page Down
• These keys move to the next or previous slide as you step through the presentation.
• Jump and quick access:
• Home, g: go to the first slide
• End, G: go to the last slide
• 1-9: jump directly to a specific slide number
• Reload and exit:
• r: reload the input Markdown file (in case you edited it during a session)
• q: quit the presentation

Configuration: customizing mdp to fit your style

mdp provides a configuration approach that recognizes the need for flexibility in color schemes, key bindings, and list presentation formats. The core of this customization is a config.h file that resides in the include/ directory of the source tree.

• What you can configure:
• Colors: choose color schemes and adjust how lists and text appear in the terminal. Note that color customization is most effective in 8-color terminal environments. If you’re in a 256-color capable terminal, you can still use the color features, but the 8-color constraint applies to certain settings.
• Keybindings: tailor the navigation or editing-like actions to your preferences. This can help if you’re more comfortable with alternative keys.
• List types: adjust how unordered lists or other list-like structures render on each slide.
• How to apply changes:
• Edit config.h to modify your desired settings, then recompile (make) to apply the changes.

Debugging mdp: building a debug version

If you’re developing or tweaking mdp, you might want to compile a debug version to inspect behavior or step through the code. The build system supports a straightforward toggle for enabling debugging features.

• Build a debug version:
• make DEBUG=1
• This prints additional information and may enable extra logging to help diagnose issues or understand how mdp renders slides.

Converting mdp slides to PDF: md2pdf

For those who want a printable or shareable PDF version of their mdp slides, md2pdf provides a bridge to convert Markdown-based slides into a PDF document. The process can involve either pre-built binaries or a Go-based tool that can fetch and integrate syntax highlighting for code blocks.

Ways to obtain md2pdf

• Install a released md2pdf tool for your OS/architecture. The project maintains a release that you can download and install.
• If you have the Go toolchain installed, you can install md2pdf using:
• go install github.com/mandolyte/mdtopdf/cmd/md2pdf@latest
• md2pdf supports mdp’s features and can pull content from local files, remote HTTP(S) URLs, or standard input.

Using md2pdf with syntax highlighting

• If you require syntax highlighting for code blocks, you can download gohighlight lexers and point md2pdf to the syntax files.
• You can customize the output with themes. For example, you can request a dark theme and enable a new page on horizontal rules, add a footer, or specify author and title metadata.

A representative example for converting a file to PDF

• The following command demonstrates converting an mdp-compatible Markdown file to a PDF with a dark theme, syntax highlighting, and structured page/slide separation:
• md2pdf -i https://github.com/jessp01/crash-course-in/raw/main/courses/aptdpkgdeb/aptdpkgdeb.md \ -o aptdpkgdeb.pdf \ -s ~/.config/zaje/syntax_files \ --theme dark \ --new-page-on-hr \ --with-footer \ --author "Jesse Portnoy jesse@packaman.io" \ --title "A crash course on handling deb packages"
• Important note: Markdown’s centering escape sequences (the -> and <- sequences) are not supported. If your source uses them, you should remove or adjust them before converting to PDF.

A practical example of preprocessing for PDF conversion

• Sometimes your Markdown source includes patterns not compatible with the conversion pipeline. A preprocessing step can help:
• sed 's@^->\s(#.)\s*<-@\1@g' sample.md | md2pdf -o mdp.pdf --theme dark --new-page-on-hr
• This approach demonstrates how to clean up the input before handing it to the converter, ensuring the output remains faithful to the intended presentation layout.

Tips for a smooth mdp experience

• Terminal color support: mdp shines when your terminal supports colors. If you’re encountering color issues or faded colors, verify that your terminal’s TERM variable is configured for color (ideally xterm-256color for full color fading features).
• Headers and display bars: the two header bars (top and bottom) provide quick context about the slide deck. The top bar usually shows the slide title, while the bottom bar presents author information or other metadata derived from theMarkdown file’s header sections.
• Performance and fidelity: mdp is designed to perform well in real-time as you navigate slides. The rendering updates happen quickly, so you can focus on your storytelling rather than fighting with the tool.
• Extensibility: the configuration system encourages experimentation. If you prefer a different color palette, or a different interaction style, you can experiment with the config.h file and rebuild to see how your preferences influence the look and feel.

A peek into the Markdown conventions

• Horizontal slide separators: the core mechanism for dividing a Markdown file into slides is the horizontal rule line. Each section separated in this way becomes a slide.
• Title and author lines: by using the header syntax with an @ prefixed line, you can designate slide-level metadata that mdp uses to fill the top and bottom bars. This makes it straightforward to present a consistent title frame and attribution across your deck.
• Rich text in slides: you can mix headlines, code blocks, lists, and quotes to construct well-structured, compelling slides. Inline formatting (bold, italic, code spans) enhances readability, while code blocks illustrate concepts or commands cleanly.

Practical workflow for building a presentation with mdp

• Start with a simple Markdown file that includes a @ Title and an @ Author line to populate the header bars.
• Divide your content into slides using horizontal rules.
• Use standard Markdown syntax to structure content inside each slide:
• Headings to establish sections
• Paragraphs with emphasis and inline code
• Code blocks for demonstrations
• Quotes for highlighting important points
• Lists for structured bullet points
• Run mdp on the file to view the slides in your terminal. Navigate with the default keys, adjust as needed, and reload when you make changes.
• If you want a PDF version for distribution or archiving, use md2pdf with the appropriate flags and options. Add syntax highlighting if your slides contain code samples.
• If you need to tweak colors or keybindings, edit config.h, rebuild, and test again.

Why choose mdp for terminal-based presentations

• Speed and simplicity: the tool is designed for quick setup and rapid iteration. You can move from content creation to live presentation without leaving the command line.
• Portability: by relying on Markdown and ncurses, mdp is highly portable across UNIX-like systems and supports a broad range of terminal emulators.
• Customizable aesthetics: even though it’s a terminal-based tool, mdp offers configurable colors and key mappings to fit your preferred workflow.
• Integration potential: because the formatting source is plain Markdown, you can store your deck in version control, share it with colleagues, or pair it with other tools that generate or process Markdown.

A closing note

mdp represents a pragmatic blend of simplicity and functionality. It embraces the ubiquity of Markdown and combines it with the accessibility of terminal-based interfaces. Whether you’re preparing a quick project briefing, teaching a small group, or delivering a tech talk on a conference notebook, mdp reduces the friction between content creation and presentation. The ability to go from a text file to a full slide deck, with optional PDF export and syntax highlighting, makes it a versatile addition to the toolkit of developers, educators, and presenters who value immediacy and reproducibility.

If you’re curious about where to start, a sensible path is to clone the repository, install the necessary ncurses headers, and experiment with sample.md to see how the header lines populate the top and bottom bars, how slides separate with horizontal rules, and how the standard controls enable you to navigate a story in a calm, controlled flow. From there, you can tailor your mdp experience through the configuration options, debug builds, and PDF export pipeline to fit your preferred publishing and presentation style.

In sum, mdp is not only about showing Markdown content on slides; it is about delivering a streamlined, dependable workflow for presenting text-heavy material in a terminal environment. Its design, geared toward speed, clarity, and portability, helps you focus on your message while the tool handles the mechanics of slide rendering, navigation, and optional export. As you gain familiarity with its conventions—from the @-prefixed headers to the reload and navigation keys—you’ll find mdp becoming a natural, efficient companion for presenting in a variety of contexts.