Skip to content

Rendering Markdown Files From Your Terminal with open_md.py

TL;DR: open_md.py is a flexible CLI tool that renders markdown files to HTML using pandoc or grip, and can open them directly on GitHub or in your browser, with support for embedded diagrams and both local and dockerized execution

Introduction#

What Is open_md.py?#

open_md.py is a command-line utility that renders markdown files with a single command and view the output immediately. The tool supports multiple rendering engines and execution backends.

Why Render Markdown Files?#

Markdown files are ubiquitous in software development and documentation, but viewing them in raw text form loses important formatting and structure open_md.py bridges this gap by:

  • Rendering markdown to styled HTML for better readability
  • Opening files directly on GitHub for sharing and collaboration
  • Supporting embedded diagrams (SVG, Graphviz, TikZ) through automatic preprocessing
  • Working both locally and in Docker containers
  • Providing live preview capabilities for iterative writing

When to Use open_md.py#

  • Documentation Review: Before committing markdown documentation, preview how it will look rendered
  • Blog Authoring: See styled output while writing blog posts
  • GitHub Navigation: Quickly open any markdown file in your repository on GitHub from the terminal
  • Live Editing: Use the grip daemon mode for live preview while editing
  • Diagram Testing: Automatically process and preview embedded diagrams

How It Works#

Rendering Modes#

The tool supports four distinct rendering modes, each with different purposes:

  • github mode: Opens the markdown file directly on GitHub in your default browser. Useful for code review and sharing links
  • pandoc mode: Converts markdown to self-contained HTML using pandoc, preserving all formatting and styles
  • grip mode: Exports markdown to HTML using grip (GitHub Flavored Markdown renderer), matching GitHub's rendering style exactly
  • grip_daemon mode: Starts grip in daemon mode, opening a live preview server in your browser that updates as you save changes

Execution Backends#

The tool can execute rendering in two environments:

  • global backend: Uses tools installed locally on your system (pandoc, grip)
  • dockerized backend: Runs tools inside a Docker container, ensuring consistent environments across machines

Preprocessing with Diagrams#

Before rendering, the tool automatically preprocesses your markdown with render_images.py to handle embedded diagrams. This means you can include SVG, Graphviz, TikZ, and other diagram formats inline in your markdown, and they'll be properly rendered in the final output

Advanced Features#

Subrepo Support#

The tool intelligently handles git subrepos and submodules. It walks up the directory tree from your file to find the closest .git directory, ensuring it opens the file in the correct repository context. This is especially useful when working with monorepos and nested projects

Diagram Preprocessing#

Embedded diagrams in your markdown are automatically detected and processed:

  • TikZ diagrams are rendered to SVG
  • Graphviz dot notation is compiled
  • Mermaid diagrams are processed (if configured)

All this happens transparently before rendering, so your final HTML contains properly rendered graphics

Docker Integration#

For the dockerized backend, the tool integrates with the project's Docker infrastructure:

  • Supports force rebuild with --dockerized-force-rebuild
  • Can use sudo if needed with --dockerized-use-sudo
  • Uses project-configured Docker images for consistency

References#