Markdown to PDF Action - Examples

This repository demonstrates the markdown-to-pdf-action with real-world examples, workflow configurations, and custom themes. Fork this repository to get started quickly or use it as a reference for your own implementation.

🚀 Quick Start

1. Fork This Repository

Click the "Fork" button at the top of this page to create your own copy.

2. Enable GitHub Actions

Go to the "Actions" tab in your fork and enable workflows.

3. Trigger a Workflow

Choose any workflow from the examples:

• Go to Actions tab
• Select a workflow from the left sidebar
• Click Run workflow
• Download the generated PDFs from the workflow artifacts

📚 What's Included

Workflow Examples

Located in .github/workflows/, these demonstrate different use cases:

Workflow	Description	Key Features
basic.yml	Simple single-file conversion	Default settings, minimal configuration
advanced.yml	Full-featured example	Custom CSS, metadata, multiple files
multi-format.yml	Different paper sizes and themes	A4/Letter, Portrait/Landscape, themes
conditional.yml	Process only changed files	Efficient CI/CD integration
scheduled.yml	Weekly documentation export	Cron scheduling, organized artifacts
pr-preview.yml	Preview docs in pull requests	PR integration, automatic comments

Sample Documents

Located in docs/ and examples/, these showcase various Markdown features:

• Basic Markdown: Headers, lists, links, emphasis
• Code Blocks: Syntax highlighting across languages
• Tables: Professional table formatting
• Images: Embedded images and diagrams
• Task Lists: Interactive checkboxes
• Emojis: GitHub-style emoji rendering
• Table of Contents: Auto-generated navigation

Custom Themes

Located in assets/css/, ready-to-use professional themes:

• professional-theme.css: Business documents with modern styling
• technical-theme.css: API docs and technical specifications
• minimal-theme.css: Clean, distraction-free reading
• executive-theme.css: Executive summaries and reports

📖 Examples by Use Case

Basic Usage

Convert a single Markdown file to PDF:

- name: Convert README to PDF
  uses: MystaMax/markdown-to-pdf@v1
  with:
      include-patterns: 'README.md'
      artifact-name: 'readme-pdf'

Try it: See .github/workflows/basic.yml

Custom Styling

Apply custom CSS for branded PDFs:

- name: Convert with custom theme
  uses: MystaMax/markdown-to-pdf@v1
  with:
      include-patterns: 'docs/**/*.md'
      css-file: 'assets/css/professional-theme.css'
      paper-size: 'A4'
      orientation: 'portrait'

Try it: See .github/workflows/advanced.yml

Multiple Formats

Generate different PDF formats from the same content:

strategy:
    matrix:
        include:
            - paper: 'A4'
              orientation: 'portrait'
              theme: 'professional'
            - paper: 'Letter'
              orientation: 'landscape'
              theme: 'technical'

Try it: See .github/workflows/multi-format.yml

CI/CD Integration

Process only changed files on pull requests:

- name: Get changed Markdown files
  uses: tj-actions/changed-files@v44
  with:
      files: '**/*.md'

- name: Convert changed files
  if: steps.changed-files.outputs.any_changed == 'true'
  uses: MystaMax/markdown-to-pdf@v1
  with:
      include-patterns: ${{ steps.changed-files.outputs.all_changed_files }}

Try it: See .github/workflows/conditional.yml

Scheduled Reports

Automate weekly documentation exports:

on:
    schedule:
        - cron: '0 9 * * 1'  # Every Monday at 9 AM

jobs:
    weekly-export:
        # ... generate PDFs with date-stamped artifacts

Try it: See .github/workflows/scheduled.yml

🎨 Customization Guide

Using Custom CSS

1. Create a CSS file in assets/css/
2. Reference it in your workflow:

with:
    css-file: 'assets/css/my-custom-theme.css'

3. See assets/css/README.md for CSS examples and tips

Front Matter Metadata

Add metadata to individual Markdown files:

---
title: "My Document Title"
author: "Your Name"
subject: "Document Category"
date: "2024-01-15"
---

# Your Content Here

File Organization

Organize PDFs in artifacts:

with:
    artifact-path-mode: 'preserve'  # Keep folder structure
    artifact-subdir: 'reports/2024'  # Organize by date

🧪 Testing Locally

While the action runs in GitHub Actions, you can test your Markdown rendering:

1. Preview Markdown: Use VS Code, GitHub, or any Markdown viewer
2. Validate CSS: Use browser dev tools to test styles
3. Check Images: Ensure all image paths are relative and files exist

📁 Repository Structure

markdown-to-pdf-action-examples/
├── README.md                          # This file
├── .github/
│   └── workflows/
│       ├── basic.yml                  # Simple example
│       ├── advanced.yml               # Full-featured example
│       ├── multi-format.yml           # Multiple outputs
│       ├── conditional.yml            # Changed files only
│       ├── scheduled.yml              # Weekly automation
│       └── pr-preview.yml             # PR integration
├── docs/
│   ├── getting-started.md             # Beginner's guide
│   ├── advanced-features.md           # Advanced usage
│   ├── api-reference.md               # API documentation style
│   ├── troubleshooting.md             # Common issues
│   └── images/
│       └── architecture-diagram.png    # Sample image
├── examples/
│   ├── basic/
│   │   ├── README.md                  # Basic example overview
│   │   └── simple-document.md         # Minimal Markdown
│   ├── code-heavy/
│   │   ├── README.md                  # Code-heavy docs overview
│   │   └── api-guide.md               # With code blocks
│   ├── with-images/
│   │   ├── README.md                  # Image example overview
│   │   ├── visual-guide.md            # Document with images
│   │   └── images/
│   │       └── sample.png             # Sample image
│   └── technical-spec/
│       ├── README.md                  # Technical doc overview
│       └── specification.md           # Technical specification
└── assets/
    ├── css/
    │   ├── README.md                  # CSS guide
    │   ├── professional-theme.css     # Business theme
    │   ├── technical-theme.css        # Technical docs theme
    │   ├── minimal-theme.css          # Minimal clean theme
    │   └── executive-theme.css        # Executive reports theme
    └── images/
        ├── logo.png                   # Example logo
        └── banner.png                 # Example banner

🎯 Common Patterns

Documentation Site

- uses: MystaMax/markdown-to-pdf@v1
  with:
      source-dir: 'docs'
      include-patterns: '**/*.md'
      exclude-patterns: '**/README.md'
      css-file: 'assets/css/professional-theme.css'
      include-toc: true

API Documentation

- uses: MystaMax/markdown-to-pdf@v1
  with:
      include-patterns: 'api-docs/**/*.md'
      css-file: 'assets/css/technical-theme.css'
      paper-size: 'Letter'
      orientation: 'landscape'

Release Notes

on:
    release:
        types: [published]

- uses: MystaMax/markdown-to-pdf@v1
  with:
      include-patterns: 'CHANGELOG.md'
      title: 'Release ${{ github.event.release.tag_name }}'
      artifact-name: 'release-notes-${{ github.event.release.tag_name }}'

🔧 Troubleshooting

No PDFs Generated

• Check the workflow logs for errors
• Verify your file patterns match existing files
• Ensure the action has proper permissions

Styling Not Applied

• Verify CSS file path is correct (relative to repository root)
• Check CSS syntax with a validator
• Use browser dev tools to test styles

Large File Warnings

• Consider splitting large documents
• Optimize images (compress, resize)
• Process files in batches

More Help

• See docs/troubleshooting.md for detailed solutions
• Check the main action repository for documentation
• Review workflow logs in the Actions tab

🤝 Contributing Examples

Have a great use case? Contributions are welcome!

1. Fork this repository
2. Add your example workflow and/or sample documents
3. Update this README with your example
4. Submit a pull request

📝 License

This example repository is provided as-is for demonstration purposes. The markdown-to-pdf-action itself is licensed under MIT.

🔗 Links

• Main Action: MystaMax/markdown-to-pdf
• Documentation: See the main repository README
• Issues: Report issues in the main repository
• Discussions: GitHub Discussions

---

Happy PDF generation! 📄✨