mkdocs-theme-topdf

a mkdocs theme to generate pdf or print.

[TOC]

Prerequiresites/ Dependency

This plugin aim to use these softwares

• mkdocs (convert markdown to html)
• python-docx (to generate docx)
• paged.js (to generate pdf, page borders and page headers)
• node.js (to generate pdf, for pagedjs-cli)

Installation - this plugin

Install this package with pip.

from PyPi

pip install mkdocs-theme-topdf

from github

pip install git+https://github.com/kuri65536/mkdocs-theme-topdf

Installation - paged.js

so paged.js uses node.js and portable chrome, it is separate from mkdocs theme.

to prepare paged.js, follow these method.

from this plugin

python -m topdf --check
> ... check node.js and npm ...
python -m topdf --setup
> ... install take long time ...
python -m topdf --test
> output report-3stamps.pdf

from manual

$ npm install pagedjs-cli
... take long time ...
$ ./node_modules/.bin/pagedjs-cli
... paged.js message ...

How to use

prepare

to use mkdocs theme see material theme documentation

setup mkdocs.yml

change mkdocs.yml to use this plugin.

site_name: the test document
theme:
    name: topdf

write markdown

write your document

$ vi docs/your/document.md

convert to html

$ ./venv/bin/mkdocs build

convert to docx

$ /path/to/python -m topdf site/your/document/index.html -o document.docx

see problem with python-docx

(old method) convert with paged.js

$ pagedjs-cli --outline-tags h1,h2,h3,h4,h5,h6 site/your/document/index.html
     -o document.pdf  # 1-line

see problem with paged.js

About PDF output

backend: python-docx

• now, I choose this solution.
• python-docx has some problems too,
  • can't handle to include SVG images
  • can't handle complex HTML. (it's my problem)
  • you need Office365 account or MS Office license to generate pdf.
  • LibreOffice and O365 output are different,
    AbiWord can't handle tables (may crash).

backend: paged.js

• I choose this for second, but not use now.
• under development.
• paged.js render the PDF with portable chrome and pupetter
  please watch out the difference of rendering results among
  them engine and your browser.
• paged.js has some problems with mkdocs outputs.
  • generated html-id is invalid for their javascript
    heading the digit aka: 1-contents
• paged.js has some problems.
  • a multi-byte problem in pdflib.js, TOC can't handle multi-byte outputs.
    I made the patch and succeed to output,
    but this cause wide sub-effects and can't fix it.
  • long tables across the pages, may break your tables.

backend: wkhtmltopdf

• I choose this for first, but not use now.
• no-longer developped.
• wkhtmltopdf render the PDF with webkit (old)
  and stable release (0.12.5) can not generate TOC with its limitation.
  wkhtmltopdf is more convinient to install, but
  I can't resolve the TOC problem and switched to paged.js

---

Demo

a sample output of PDF with paged.js

About scripts and styles

please see the report sample

FAQ

can not open docx in AbiWord

: In my experience, AbiWord can not open python-docx tables,
please use LibreOffice. this is an AbiWord limitation.

History

{: .before-dl-table .table2-8 }

version : descriptions

1.3.0 : - import SVG to docx.

1.2.0 : - fix parsing strong elements at heads of paragraphs. - enable tests.

1.1.3 : first version of footnotes2.

1.1.2 : - enable table styles to normal table. - enable tables detail width (for docx only). - enable tables auto width for docx.

1.1.1 : bugfix for 3stamps, br elements. and add support for sup elements.

1.1.0 : append controls for presensation.

1.0.2 : ignore katex outputs/ start to implement footnotes2.

1.0.1 : enable styles for code / reduce file size by styles/ auto numbers

1.0.0 : update to github/ nested lists/ hr as page-breaks

0.9.6 : enable inline elements: comments, em, br, strong or etc...

0.9.5 : support embedded images.

0.9.4 : enable ooxml fields: TOC, page numbers, bookmarks

0.9.3 : borders on code blocks/ control tables width/ floating rectangles on header

0.9.2 : borders on code blocks/ control tables width.

0.9.1 : enable document numbers on header

0.9.0 : append docx backend by python-docx

0.5.1 : fixed multiple <tbody> element in dl-tables.

0.5.0 : add a script: fix the mkdocs invalid html-id to prevent paged-js exceptions.

0.4.0 : append CSS-counters for figures and tables.

0.3.0 : append theme to the package name

0.2.7 : TOC and styles

0.2.6 : append explanation for paged.js TOC and styles

0.2.5 : append explanation for paged.js styles

0.2.4 : append explanation for paged.js styles

0.2.3 : append slash line to the no-stamp cells.

0.2.2 : append screenshot

0.2.1 : append explanation for dl-dt-dd tables

0.2.0 : start to edit/ 3stamps

0.1.2 : start to use paged.js

0.1.1 : start to use mkhtmltopdf

0.1.0 : append dl-dt-dd tables

0.0.6 : start to edit

Donations

If you are feel to nice for this software, please donation to my

• Bitcoin | 19AyoXxhm8nzgcxgbiXNPkiqNASfc999gJ |
• Ether | 0x3a822c36cd5184f9ff162c7a55709f3d6d861608 |
• or librapay, I'm glad from smaller (about $1)