{"id":28505694,"url":"https://github.com/kuri65536/mkdocs-theme-topdf","last_synced_at":"2025-07-04T22:31:44.311Z","repository":{"id":57442177,"uuid":"229689674","full_name":"kuri65536/mkdocs-theme-topdf","owner":"kuri65536","description":"A mkdocs theme for create PDF and printing with paged.js","archived":false,"fork":false,"pushed_at":"2025-05-22T04:08:14.000Z","size":343,"stargazers_count":13,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-08T19:37:22.434Z","etag":null,"topics":["mkdocs-theme"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kuri65536.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"liberapay":"kuri65536","custom":["https://kuri65536.bitbucket.io/donation.html?label=github-mkdocs-theme-topdf"]}},"created_at":"2019-12-23T06:20:31.000Z","updated_at":"2025-05-22T04:08:18.000Z","dependencies_parsed_at":"2025-05-22T05:30:10.124Z","dependency_job_id":null,"html_url":"https://github.com/kuri65536/mkdocs-theme-topdf","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kuri65536/mkdocs-theme-topdf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuri65536%2Fmkdocs-theme-topdf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuri65536%2Fmkdocs-theme-topdf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuri65536%2Fmkdocs-theme-topdf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuri65536%2Fmkdocs-theme-topdf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kuri65536","download_url":"https://codeload.github.com/kuri65536/mkdocs-theme-topdf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuri65536%2Fmkdocs-theme-topdf/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263627954,"owners_count":23490878,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mkdocs-theme"],"created_at":"2025-06-08T19:30:37.468Z","updated_at":"2025-07-04T22:31:44.302Z","avatar_url":"https://github.com/kuri65536.png","language":"Python","funding_links":["https://liberapay.com/kuri65536","https://kuri65536.bitbucket.io/donation.html?label=github-mkdocs-theme-topdf"],"categories":[],"sub_categories":[],"readme":"mkdocs-theme-topdf\n=========================================================\na mkdocs theme to generate pdf or print.\n\n[TOC]\n\n\nPrerequiresites/ Dependency\n--------------------------\nThis plugin aim to use these softwares\n\n- mkdocs (convert markdown to html)\n- python-docx (to generate docx)\n- paged.js (to generate pdf, page borders and page headers)\n- node.js (to generate pdf, for pagedjs-cli)\n\n\n\nInstallation - this plugin \u003c!-- {{{1 --\u003e\n--------------------------\nInstall this package with pip.\n\n### from PyPi\n```bash\npip install mkdocs-theme-topdf\n```\n\n### from github\n```bash\npip install git+https://github.com/kuri65536/mkdocs-theme-topdf\n```\n\n\nInstallation - paged.js\n--------------------------\nso paged.js uses node.js and portable chrome,\nit is separate from mkdocs theme.\n\nto prepare paged.js, follow these method.\n\n### from this plugin\n```bash\npython -m topdf --check\n\u003e ... check node.js and npm ...\npython -m topdf --setup\n\u003e ... install take long time ...\npython -m topdf --test\n\u003e output report-3stamps.pdf\n```\n\n### from manual\n```bash\n$ npm install pagedjs-cli\n... take long time ...\n$ ./node_modules/.bin/pagedjs-cli\n... paged.js message ...\n```\n\n\n\nHow to use \u003c!-- {{{1 --\u003e\n--------------------------\n### prepare\nto use mkdocs theme see [material theme documentation][mkdocs-theme]\n\n[mkdocs-theme]: https://squidfunk.github.io/mkdocs-material/getting-started/\n\n### setup mkdocs.yml\nchange mkdocs.yml to use this plugin.\n\n```yaml\nsite_name: the test document\ntheme:\n    name: topdf\n```\n\n### write markdown\nwrite your document\n\n```bash\n$ vi docs/your/document.md\n```\n\n\n### convert to html\n```bash\n$ ./venv/bin/mkdocs build\n```\n\n\n### convert to docx \u003c!-- {{{1 --\u003e\n```bash\n$ /path/to/python -m topdf site/your/document/index.html -o document.docx\n```\n\nsee [problem with python-docx](#backend-python-docx)\n\n\u003cimg src=\"https://user-images.githubusercontent.com/11357613/86648803-245e5280-c01c-11ea-98fc-64cdcd73c399.png\"\n  style=\"max-width: 100%;\" /\u003e\n\n\n\n### (old method) convert with paged.js\n\n```bash\n$ pagedjs-cli --outline-tags h1,h2,h3,h4,h5,h6 site/your/document/index.html\n     -o document.pdf  # 1-line\n```\n\nsee [problem with paged.js](#backend-paged-js)\n\n\u003cimg src=\"https://user-images.githubusercontent.com/11357613/70920996-cf9ac080-2066-11ea-81f2-0e7c840ebea1.png\"\n  style=\"max-width: 100%;\" /\u003e\n\n\n\n### About PDF output\n\n#### backend: python-docx\n- now, I choose this solution.\n- python-docx has some problems too,\n    - can't handle to include SVG images\n    - can't handle complex HTML. (it's my problem)\n    - you need Office365 account or MS Office license to generate pdf.\n    - LibreOffice and O365 output are different,  \n        AbiWord can't handle tables (may crash).\n\n\n#### backend: paged.js\n- I choose this for second, but not use now.\n- under development.\n- paged.js render the PDF with portable chrome and pupetter  \n    please watch out the difference of rendering results among  \n    them engine and your browser.\n- paged.js has some problems with mkdocs outputs.\n    - generated html-id is invalid for their javascript  \n        heading the digit aka: `1-contents`\n- paged.js has some problems.\n    - a multi-byte problem in pdflib.js, TOC can't handle multi-byte outputs.  \n        I made the patch and succeed to output,  \n        but this cause wide sub-effects and can't fix it.\n    - long tables across the pages, may break your tables.\n\n\n#### backend: wkhtmltopdf\n- I choose this for first, but not use now.\n- no-longer developped.\n- wkhtmltopdf render the PDF with webkit (old)  \n    and stable release (0.12.5) can not generate TOC with its limitation.  \n    wkhtmltopdf is more convinient to install, but  \n    I can't resolve the TOC problem and switched to paged.js\n\n\n\n---\n\n\n\nDemo \u003c!-- {{{1 --\u003e\n--------------------------\n[a sample output of PDF with paged.js](https://github.com/kuri65536/mkdocs-theme-topdf/files/3993873/report-3stamps.pdf)\n\n\n![screenshot in Android Word](https://user-images.githubusercontent.com/11357613/86648803-245e5280-c01c-11ea-98fc-64cdcd73c399.png)\n\n\n![screenshot in pdf viewer](https://user-images.githubusercontent.com/11357613/70920996-cf9ac080-2066-11ea-81f2-0e7c840ebea1.png)\n\n\n\nAbout scripts and styles\n--------------------------\nplease see [the report sample](test/docs/report-3stamps.md)\n\n\n\nFAQ\n--------------------------\ncan not open docx in AbiWord\n\n: In my experience, AbiWord can not open python-docx tables,  \n    please use LibreOffice. this is an AbiWord limitation.\n\n\n\nHistory \u003c!-- {{{1 --\u003e\n--------------------------\n\u003c!-- this comment is needed for paragraph class --\u003e\n{: .before-dl-table .table2-8 }\n\nversion\n: descriptions\n\n1.3.0\n:   - import SVG to docx.\n\n1.2.0\n:   - fix parsing strong elements at heads of paragraphs.\n    - enable tests.\n\n1.1.3\n:   first version of footnotes2.\n\n1.1.2\n:   - enable table styles to normal table.\n    - enable tables detail width (for docx only).\n    - enable tables auto width for docx.\n\n1.1.1\n: bugfix for 3stamps, br elements. and add support for sup elements.\n\n1.1.0\n: append controls for presensation.\n\n1.0.2\n: ignore katex outputs/ start to implement footnotes2.\n\n1.0.1\n: enable styles for `code` / reduce file size by styles/ auto numbers\n\n1.0.0\n: update to github/ nested lists/ hr as page-breaks\n\n0.9.6\n: enable inline elements: comments, em, br, strong or etc...\n\n0.9.5\n: support embedded images.\n\n0.9.4\n: enable ooxml fields: TOC, page numbers, bookmarks\n\n0.9.3\n: borders on code blocks/ control tables width/ floating rectangles on header\n\n0.9.2\n: borders on code blocks/ control tables width.\n\n0.9.1\n: enable document numbers on header\n\n0.9.0\n: append docx backend by python-docx\n\n0.5.1\n: fixed multiple `\u003ctbody\u003e` element in dl-tables.\n\n0.5.0\n: add a script: fix the mkdocs invalid html-id to prevent paged-js exceptions.\n\n0.4.0\n: append CSS-counters for figures and tables.\n\n0.3.0\n: append `theme` to the package name\n\n0.2.7\n: TOC and styles\n\n0.2.6\n: append explanation for paged.js TOC and styles\n\n0.2.5\n: append explanation for paged.js styles\n\n0.2.4\n: append explanation for paged.js styles\n\n0.2.3\n: append slash line to the no-stamp cells.\n\n0.2.2\n: append screenshot\n\n0.2.1\n: append explanation for dl-dt-dd tables\n\n0.2.0\n: start to edit/ 3stamps\n\n0.1.2\n: start to use paged.js\n\n0.1.1\n: start to use mkhtmltopdf\n\n0.1.0\n: append dl-dt-dd tables\n\n0.0.6\n: start to edit\n\n\n\nDonations\n---------------------\nIf you are feel to nice for this software, please donate to\n\n[![img-bitcoin]][lnk-bitcoin]\n\u0026nbsp;\u0026nbsp;or\u0026nbsp;\u0026nbsp;\n[![img-etherium]][lnk-bitcoin]\n\n- [bitcoin:39Qx9Nffad7UZVbcLpVpVanvdZEQUanEXd][lnk-bitcoin]\n- [ethereum:0x9d03b1a8264023c3ad8090b8fc2b75b1ba2b3f0f][lnk-bitcoin]\n- or [liberapay](https://liberapay.com/kuri65536) .\n\n[lnk-bitcoin]:  https://kuri65536.bitbucket.io/donation.html?message=thank-for-mkdocs_theme_topdf\n[img-bitcoin]:  https://github.com/user-attachments/assets/abce4347-bcb3-42c6-a9e8-1cd12f1bd4a5\n[img-etherium]: https://github.com/user-attachments/assets/d1bdb9a8-9c6f-4e74-bc19-0d0bfa041eb2\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuri65536%2Fmkdocs-theme-topdf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuri65536%2Fmkdocs-theme-topdf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuri65536%2Fmkdocs-theme-topdf/lists"}