Convert Markdown Documentation to PDF for Client Handover

Alright, let’s talk about that last mile of a project: client handover. I remember one too many times my team would write beautiful, comprehensive documentation in Markdown, right in the repo where it belongs. Then came the painful part: manually copying it all into a document, fighting with formatting for hours, and exporting a PDF that looked… okay. It was a time sink and always felt unprofessional. That’s why I built this workflow. It’s a simple script that turns our pristine Markdown into a polished, branded PDF automatically. It saves me a couple of hours per project and ensures our clients get a consistent, high-quality document every single time.

Prerequisites

Before we dive in, make sure you have a few things ready. I’m assuming you’re comfortable with basic Python environments.

• Python 3.x installed on your machine.
• A couple of Python libraries. You’ll need to install them using pip. In your terminal, you’d run something like pip install markdown2 WeasyPrint.
• Your documentation, written in one or more Markdown (.md) files.
• (Optional) A CSS file for styling if you want to add company branding. I highly recommend this.

A quick heads-up: WeasyPrint is a powerful library, but it relies on some system-level dependencies (Pango and Cairo) to work its magic. If you’re on a Debian-based system like Ubuntu, you’ll likely need to install them first. A command like sudo apt-get install libpango-1.0-0 libcairo2 usually does the trick. Check the WeasyPrint documentation for your specific OS.

The Step-by-Step Guide

I’ll skip the standard virtualenv setup since you likely have your own workflow for that. Let’s jump straight to the logic. I typically organize my project with a structure like this: a main script (e.g., generate_docs.py), a source_docs/ directory for the input Markdown files, and a build/ directory for the generated PDFs.

Step 1: The Core Python Script

First, let’s create our Python script. We’ll call it generate_docs.py. The script will find all Markdown files in our source directory, convert each one to HTML, and then render that HTML as a PDF in our build directory.

Here’s the code. The real power here is in combining two libraries: markdown2 handles the conversion to HTML, and WeasyPrint does the heavy lifting of turning that HTML into a beautiful PDF.

import os
import markdown2
from weasyprint import HTML

# --- Configuration ---
SOURCE_DIR = 'source_docs'
OUTPUT_DIR = 'build'
# ---------------------

def convert_markdown_to_pdf():
    """
    Finds all Markdown files in the source directory,
    converts them to PDF, and saves them in the output directory.
    """
    print("Starting documentation conversion...")

    # Ensure the output directory exists
    if not os.path.exists(OUTPUT_DIR):
        os.makedirs(OUTPUT_DIR)
        print(f"Created output directory: {OUTPUT_DIR}")

    # Find all .md files in the source directory
    try:
        markdown_files = [f for f in os.listdir(SOURCE_DIR) if f.endswith('.md')]
    except FileNotFoundError:
        print(f"Error: Source directory '{SOURCE_DIR}' not found. Please create it and add your .md files.")
        return

    if not markdown_files:
        print("No Markdown files found to convert.")
        return

    for md_file in markdown_files:
        # Construct the full paths
        md_file_path = os.path.join(SOURCE_DIR, md_file)
        pdf_file_name = os.path.splitext(md_file)[0] + '.pdf'
        pdf_file_path = os.path.join(OUTPUT_DIR, pdf_file_name)

        print(f"Processing '{md_file_path}' -> '{pdf_file_path}'")

        # Read the content of the markdown file
        with open(md_file_path, 'r', encoding='utf-8') as f:
            md_content = f.read()

        # Convert markdown to HTML
        # Using 'fenced-code-blocks' and 'tables' for common README features
        html_content = markdown2.markdown(md_content, extras=['fenced-code-blocks', 'tables'])

        # Create a PDF from the HTML content
        HTML(string=html_content).write_pdf(pdf_file_path)

    print(f"\nConversion complete! {len(markdown_files)} PDFs created in '{OUTPUT_DIR}'.")

if __name__ == '__main__':
    convert_markdown_to_pdf()

Step 2: Adding Custom Styling

This is where you go from a basic document to a professional-looking handover. Create a CSS file, let’s call it style.css, in your project’s root directory. You can add your company’s fonts, colors, and even logos.

Here’s a simple example style.css to get you started:

/* Basic styles for the document body */
body {
    font-family: 'Helvetica', 'Arial', sans-serif;
    line-height: 1.6;
    color: #333;
}

h1, h2, h3 {
    font-family: 'Georgia', serif;
    color: #1a2c42; /* A professional dark blue */
    border-bottom: 1px solid #eee;
    padding-bottom: 5px;
}

/* Style for code blocks */
pre {
    background-color: #f4f4f4;
    border: 1px solid #ddd;
    border-radius: 4px;
    padding: 1em;
    white-space: pre-wrap; /* Ensures long lines wrap */
    word-wrap: break-word;
}

code {
    font-family: 'Courier New', monospace;
}

Now, let’s update our Python script to use this stylesheet. It’s a one-line change. We just import the CSS object from WeasyPrint and pass our stylesheet to the write_pdf method.

# ... (imports at the top of the script)
from weasyprint import HTML, CSS

# ... (inside the for loop)

# Create a PDF from the HTML content, now with our custom stylesheet
# This assumes 'style.css' is in the same directory as the script.
stylesheet = os.path.join(os.path.dirname(__file__), 'style.css')
HTML(string=html_content).write_pdf(pdf_file_path, stylesheets=[CSS(stylesheet)])

Pro Tip: For truly professional documents, I always add a header with our company logo and a footer with the date and page numbers. You can do this with CSS Paged Media rules like @page { @top-center { content: "TechResolve Project Documentation"; } }. It’s a small touch that makes a huge difference in client perception.

Where I Usually Mess Up (Common Pitfalls)

• WeasyPrint Dependencies: The number one place people get stuck is with the system dependencies I mentioned earlier. If the script fails with a cryptic error about a missing library (like `libpango` or `cairo`), it’s almost always this. Don’t skip that part of their installation guide.
• Pathing Problems: Relative paths can be a headache. If the script complains it can’t find your CSS file or source directory, it’s because you’re running it from an unexpected location. Using absolute paths with os.path.abspath or carefully constructing them with os.path.join as I did in the script is the best way to avoid this.
• CSS Not Applying: If your styles aren’t showing up, first double-check that the path to your style.css file is correct in the script. The second most common reason is that your CSS selectors don’t match the HTML generated by markdown2. A good debug step is to temporarily save the html_content variable to a file (e.g., debug.html) and open it in a browser to inspect the elements.

Conclusion

And that’s the whole workflow. It’s a straightforward, repeatable process to turn your team’s hard work in Markdown into a professional PDF ready for any client or stakeholder. This is one of those small automations that pays off big in consistency, professionalism, and most importantly, saved time. Now you can focus on the engineering, knowing the documentation will handle itself.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions