Skip to content

v2.6.4

Choose a tag to compare

View all tags
@TobiasGlaubach TobiasGlaubach released this 22 May 14:24
· 50 commits to main since this release
v2.6.4
fe24fd8
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Release Notes — pydocmaker v2.6.4

NOTE: Release notes were auto created using "Qwen3.6-35B-A3B-FP8" Model

Version: 2.6.4
Branch: dev_20260519 → main
Date: 2026-05-22

Overview

This release introduces significant enhancements to the Typst template system, including new professional report and paper templates, improved template variable detection, automatic logo embedding, and better engine/template format handling in PDF generation.

New Features

New Typst Templates

Three new Typst templates are now available for generating professional-looking PDF documents:

  • report.typ.j2 — A full-featured report template with:

    • Professional title page with logo placement
    • Configurable header/footer strings (left/right)
    • Multi-language table of contents (DE, EN, FR, ES, IT, NL, PT, ZH, JA, RU, AR)
    • Lists of figures, tables, acronyms, applicables, and references
    • Compact mode for space-constrained documents
    • Automatic pydocmaker watermark/link
    • Base64-encoded logo support via @preview/based:0.2.0

  • paper.typ.j2 — A concise paper template with:

    • Two-column layout
    • Author grid with affiliation and email links
    • Abstract section
    • Minimal styling for academic/scientific papers

  • __myreport.typ.j2 — A simplified report template with:

    • Single-column layout
    • Table of contents with figure/table listings
    • Reference document sections

Automatic Logo Embedding

The Typst backend now automatically embeds the pydocmaker logo when:

  • The logo_b64_pydocmaker variable is not explicitly provided
  • The template declares logo_b64_pydocmaker as an expected variable

This is handled via the new b64_data.py module which contains the base64-encoded pydocmaker logo.

Improved Template Variable Detection

The templating.py module now includes robust find_undeclared_variables() implementation that:

  • Safely extracts source text from various template object types (string, file, Jinja2 Template)
  • Handles edge cases where templates are loaded from different sources
  • Auto-populates template parameters with None for undeclared variables

Engine/Template Format Auto-Detection

The to_pdf() method in core.py now:

  • Automatically switches the PDF engine when the document's template format doesn't match the requested engine
  • Uses raise_on_error=True to detect template format mismatches and fall back gracefully
  • Supports engine.startswith('typ') for flexible Typst engine matching

Binary Attachment Support in Typst Compilation

The Typst backend now supports binary attachments (images, files) via:

  • New attachments parameter in compile_with_typst()
  • Automatic temporary directory creation for binary file handling
  • Support for bytes, Path, and string file paths

API Changes

New Exports

  • pandoc_convert — Now exported from pydocmaker.backend.pandoc_api and available as a top-level import from pydocmaker

Modified Functions

Function Change
Doc.get_template_from_meta() Added raise_on_error parameter; now uses meta.pop() for cleaner extraction
Doc.set_template_to_meta() Added template_params parameter for additional template parameters
Doc.to_typst() Now uses tformat='typ' instead of 'typst'; merges params from meta automatically
Doc.to_pdf() Added engine auto-switching; Typst path now uses ret_attachments=True
templating.DocTemplate.from_tid() Added tformat=None guard; auto-populates params for undeclared variables
templating.DocTemplate.find_undeclared_variables() Complete rewrite for robust source extraction
templating.DocTemplate.tformat New property to extract template format from template_id
ex_typst.convert() Added ret_attachments parameter; auto-embeds logo; handles libraries
ex_typst.compile_with_typst() Added attachments parameter; refactored into _compile() helper
_handle_template() Now returns 3 values: (template_obj, attachments, template_str)

Removed Code

  • version auto-generation from revision (removed from ex_typst.py)
  • Author JSON serialization in ex_typst.py (no longer needed)

Bug Fixes

  • HTML template: Added default("Empty") filter to title to prevent empty <title> tags
  • Table headers: Typst table headers are now wrapped in #strong[] for proper bold rendering
  • Trailing newline: Removed trailing whitespace in util.py

Internal Improvements

  • baseformatter.py: _handle_template() now returns template_str for variable detection
  • pandoc_api.py: Added comprehensive docstring to pandoc_convert()
  • core.py: Added copy.deepcopy() for metadata safety in get_template_from_meta()
  • core.py: Fixed typo in docstring ("defalt" → "default")

Files Changed

File Type Lines
src/pydocmaker/__init__.py Modified +4/-1
src/pydocmaker/b64_data.py New +8
src/pydocmaker/backend/baseformatter.py Modified +16/-2
src/pydocmaker/backend/ex_html.py Modified +2/-1
src/pydocmaker/backend/ex_rich.py Modified +4/-1
src/pydocmaker/backend/ex_tex.py Modified +3/-1
src/pydocmaker/backend/ex_typst.py Modified +292/-170
src/pydocmaker/backend/pandoc_api.py Modified +26
src/pydocmaker/core.py Modified +78/-30
src/pydocmaker/templates/__myreport.typ.j2 New +179
src/pydocmaker/templates/base.html.j2 Modified +2/-1
src/pydocmaker/templates/paper.typ.j2 New +125
src/pydocmaker/templates/report.typ.j2 New +448
src/pydocmaker/templating.py Modified +46/-2
src/pydocmaker/util.py Modified +1/-1

Total: +1035 insertions, -199 deletions across 15 files

Migration Notes

For Existing Users

  1. Template format strings: If you were using tformat='typst', consider updating to tformat='typ' for consistency with the new template format detection.

  2. Custom templates: If you have custom Typst templates that use logo_b64_pydocmaker, the logo will now be automatically provided. If you want to suppress it, set hide_pydocmaker=True in your template parameters.

  3. Binary attachments: To include binary files (images, etc.) in Typst-generated PDFs, use the new attachments parameter:

    doc.to_pdf(attachments={'logo.png': open('logo.png', 'rb')})

For Template Authors

  • The find_undeclared_variables() method now works reliably with all template source types. Use it to discover which variables your template expects.
  • The tformat property on DocTemplate can be used to determine the expected format of a template.
Assets 2
Loading