armin/md2pdf

Converts multiple markdown files to HTML and PDF.

0.2.1 2023-05-24 12:12 UTC

Requires

• php: ^8.1
• ext-iconv: *
• ext-json: *
• league/commonmark: ^2.0
• mpdf/mpdf: ^8.1
• scrivo/highlight.php: ^9.18
• symfony/console: ^5.4 || ^6.2
• symfony/finder: ^5.4 || ^6.2
• symfony/options-resolver: ^5.4 || ^6.2
• symfony/yaml: ^5.4 || ^6.2

Requires (Dev)

• armin/editorconfig-cli: ^1.5
• friendsofphp/php-cs-fixer: ^3.16
• jangregor/phpstan-prophecy: ^1.0
• phpstan/phpstan: ^1.10.15
• phpunit/phpunit: ^9.5
• seld/phar-utils: ^1.1

MIT

• Armin Vieweg

README

PHP application to convert multiple markdown files to HTML and PDF.

It's a more simple alternative to e.g. pandoc.

This is a very early prototype! Without any release, yet.

Documentation

Checkout the full Documentation in this repository or checkout the rendered PDF version (TODO).

First steps

Download the latest phar binary or add this package (armin/md2pdf) to your composer.json.

When using Composer to require the package, you can access the binary on CLI using:

vendor/bin/md2pdf

Now, you need to create md2pdf.yaml file in your project's root directory.

Minimum example:

title: Test Document
author: Armin Vieweg
baseUrl: https://github.com/a-r-m-i-n/md2pdf/blob/master
rootPath: .
structure:
  - section: Documentation
    level: 1
  - docs/index.md
  - docs/configuration.md
  - section: README Contents
    level: 1
  - README.md

output: md2pdf-documentation.pdf

In this file, we define the structure of the HTML/PDF output. We can also separate contents, using sections.

Now, you can simply run:

vendor/bin/md2pdf build

Early version

As already mentioned before, this is a very early prototype. The code needs heavy refactoring, some functionality is not working properly or still missing entirely.

It is planned to implement four modes you can choose from:

• init - to kickstart initial md2pdf.yaml file
• check - for new and missing files in structure
• update - update md2pdf.yaml structure (apply results from check)
• build - create the actual output

Currently, the build mode is the only implemented one.

Features

• Merge configured markdown structure (files) and convert to HTML (using league/commonmark)
• Provide extended anchors (including sanitized filename)
• Replace relative links to documentation by extended anchors (does not work properly, yet)
• Prepend configured baseUrl to relative links to files in repository (which are not part of the configured markdwn structure)
• Provide table of content for every headline (with page numbers, good for printing)
• Provide bookmarks for every headline (good for PDF readers)
• Add custom sections to structure to separate contents
  • Level customizable (starts with 1)
  • You can also pass additional formatted texts, using the contents sub-key, which accepts markdown formatted input
• Syntax highlighting for embedded code (configurable, using scrivo/highlight.php)
• Configurable styles
• Manual page-breaks and orientation changes possible (<!-- PAGEBREAK --> <!-- PAGEBREAK:L --> <!-- PAGEBREAK:P -->)
• Output converted markdown contents (via HTML) to PDF (using mpdf/mpdf)
• Phar compiler
  • because of filesize reasons, only the TTF fonts "DejaVuSerif" and "DejaVuSans" are included to phar binary

Missing

• Modes: init, check and update
• Refactored analyzing of relative links in markdown content
• PDF setup
  • sizes, borders, etc
  • path to custom fonts
• ability to also save the HTML file
• configuration to disable bookmarks
• cleanup (remove tmp dir)
• complete documentation