A Docker container for converting Markdown files to high-quality PDFs using Pandoc and XeLaTeX.
- Easy Conversion: Transform Markdown files into professional PDFs effortlessly.
- High-Quality Output: Leverages XeLaTeX and custom fonts for superior typography and Unicode support.
- Fully Featured: Pre-installed with Pandoc, extensive LaTeX packages, and fonts for comprehensive PDF generation.
- Customizable: Modify the Dockerfile to suit your specific needs or extend functionality.
- Pipeline Ready: Ideal for integration into CI/CD pipelines or automated documentation workflows.
- Getting Started
- Usage
- Examples
- Building the Docker Image
- Customization
- Contributing
- License
- Acknowledgments
- Docker: Ensure Docker is installed on your system. Get Docker
Pull the Docker image from Docker Hub:
docker pull containercraft/pandocOr build the image locally using the provided Dockerfile:
docker build --progress plain --tag containercraft/pandoc -f Dockerfile .To convert a Markdown file (my_document.md) to PDF:
docker run --rm -v $(pwd):/convert containercraft/pandoc my_document.md--rm: Automatically removes the container after execution.-v $(pwd):/convert: Mounts the current directory into the container.my_document.md: The Markdown file to convert.
The generated PDF (my_document.pdf) will be saved in your current directory.
The container uses an entrypoint script (pandoc-entrypoint) with the following Pandoc command:
pandoc my_document.md -o my_document.pdf \
-V mainfont="Noto Serif" \
-V monofont="Noto Mono" \
-V geometry:margin=1in \
--highlight-style=kate \
--pdf-engine=xelatex \
--toc -N-V mainfont="Noto Serif": Sets the main text font.-V monofont="Noto Mono": Sets the monospaced font.-V geometry:margin=1in: Sets document margins.--highlight-style=kate: Applies syntax highlighting style.--pdf-engine=xelatex: Uses XeLaTeX for better 8000 font and Unicode support.--toc: Includes a table of contents.-N: Numbers the sections.
To customize the conversion process, you can:
- Modify the Entrypoint Script: Adjust
pandoc-entrypointwith your preferred options. - Run Pandoc Directly: Access the container's shell and run Pandoc commands manually.
docker run --rm -it -v $(pwd):/convert containercraft/pandoc /bin/bashOnce inside the container:
pandoc my_document.md -o my_document.pdf [your options]Convert all Markdown files in a directory:
for file in *.md; do
docker run --rm -v $(pwd):/convert containercraft/pandoc "$file"
doneUse the container in automated workflows:
GitHub Actions Example:
jobs:
build_pdf:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Convert Markdown to PDF
run: |
docker run --rm -v ${{ github.workspace }}:/convert containercraft/pandoc my_document.mdGitLab CI/CD Example:
pdf_generation:
image: containercraft/pandoc
script:
- pandoc my_document.md -o my_document.pdf
artifacts:
paths:
- my_document.pdfClone the repository and build the image:
git clone https://github.com/yourusername/pandoc-docker.git
cd pandoc-docker
docker build --progress plain --tag containercraft/pandoc -f Dockerfile .- Add Packages: Include additional LaTeX packages or fonts by modifying the
APT_PKGSvariable. - Change Entrypoint: Update
pandoc-entrypointto alter default Pandoc options.
- Install Additional Tools: Install tools like
tesseract-ocrfor OCR capabilities. - Integrate Filters: Add Pandoc filters or Lua scripts for advanced processing.
Contributions are welcome! Please:
- Fork the Repository: Click the "Fork" button on GitHub.
- Create a Feature Branch:
git checkout -b feature/your-feature - Commit Your Changes:
git commit -m 'Add your feature' - Push to the Branch:
git push origin feature/your-feature - Open a Pull Request: Describe your changes and submit.
- Markdown 2 PDF Blog by jdhao.github.io
- Pandoc: Universal document converter.
- LaTeX Project: High-quality typesetting system.
- Docker: Containerization platform.