{"id":32135296,"url":"https://github.com/solworktech/md2pdf","last_synced_at":"2025-10-21T03:58:15.784Z","repository":{"id":28874809,"uuid":"116139841","full_name":"solworktech/md2pdf","owner":"solworktech","description":"A CLI utility that generates PDFs from Markdown. Features:  syntax highlighting (for code blocks), dark, light and custom themes, TOC autogeneration,tables, pagination control (using horizontal lines - especially useful for presentations), page Footer (consisting of author, title and page number), support of non-Latin charsets and multiple font","archived":false,"fork":false,"pushed_at":"2025-06-10T18:34:32.000Z","size":7401,"stargazers_count":194,"open_issues_count":3,"forks_count":35,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-09-16T19:55:08.767Z","etag":null,"topics":["cli","convert","footer","golang","markdown","md2pdf","mdtopdf","pagination","pdf-generation","syntax-highlighting","themes","toc-generator","utility"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/solworktech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2018-01-03T13:27:38.000Z","updated_at":"2025-09-14T12:11:35.000Z","dependencies_parsed_at":"2024-12-18T16:22:13.216Z","dependency_job_id":"8fd8075c-61d6-405e-a8a7-de94ce5fd1fa","html_url":"https://github.com/solworktech/md2pdf","commit_stats":null,"previous_names":["solworktech/mdtopdf","mandolyte/mdtopdf","solworktech/md2pdf"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/solworktech/md2pdf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solworktech%2Fmd2pdf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solworktech%2Fmd2pdf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solworktech%2Fmd2pdf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solworktech%2Fmd2pdf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/solworktech","download_url":"https://codeload.github.com/solworktech/md2pdf/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/solworktech%2Fmd2pdf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":280200870,"owners_count":26289477,"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","status":"online","status_checked_at":"2025-10-21T02:00:06.614Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cli","convert","footer","golang","markdown","md2pdf","mdtopdf","pagination","pdf-generation","syntax-highlighting","themes","toc-generator","utility"],"created_at":"2025-10-21T03:58:11.765Z","updated_at":"2025-10-21T03:58:15.772Z","avatar_url":"https://github.com/solworktech.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CI][badge-build]][build]\n[![GoDoc][go-docs-badge]][go-docs]\n[![GoReportCard][go-report-card-badge]][go-report-card]\n[![License][badge-license]][license]\n\n## Markdown to PDF\n\nA CLI utility which, as the name implies, generates a PDF from Markdown.\n\nThis package depends on two other packages:\n- [gomarkdown](https://github.com/gomarkdown/markdown) parser to read the markdown source\n- [fpdf](https://codeberg.org/go-pdf/fpdf) to generate the PDF\n\n## Features\n\n- [Syntax highlighting (for code blocks)](#syntax-highlighting)\n- [Dark and light themes](#custom-themes)\n- [Customised themes (by passing a JSON file to `md2pdf`)](#custom-themes)\n- [Auto Generation of Table of Contents](#auto-generation-of-table-of-contents)\n- [Support of non-Latin charsets and multiple fonts](#using-non-ascii-glyphsfonts)\n- [Pagination control (using horizontal lines - especially useful for presentations)](#additional-options)\n- [Page Footer (consisting of author, title and page number)](#additional-options)\n\n## Supported Markdown elements\n\n- Emphasised and strong text \n- Headings 1-6\n- Ordered and unordered lists\n- Nested lists\n- Images\n- Tables\n- Links\n- Code blocks and backticked text\n\n## Installation \n\nYou can obtain the pre-built `md2pdf` binary for your OS and arch\n[here](https://github.com/solworktech/md2pdf/releases); \nyou can also install the `md2pdf` binary directly onto your `$GOBIN` dir with:\n\n```sh\n$ go install github.com/solworktech/md2pdf/v2/cmd/md2pdf@latest\n```\n\n`md2pdf` is also available via [Homebrew](https://formulae.brew.sh/formula/md2pdf):\n\n```sh\n$ brew install md2pdf\n```\n\n## Syntax highlighting\n\n`md2pdf` supports colourised output via the [gohighlight module](https://github.com/jessp01/gohighlight).\n\nFor examples, see [testdata/syntax_highlighting.md](./testdata/syntax_highlighting.md) and \n[testdata/syntax_highlighting.pdf](./testdata/syntax_highlighting.pdf)\n\n## Custom themes\n\n`md2pdf` supports both light and dark themes out of the box (use `--theme light` or `--theme dark` - no config required). \n\nHowever, if you wish to customise the font faces, sizes and colours, you can use the JSONs in\n[custom_themes](./custom_themes) as a starting point. Edit to your liking and pass `--theme /path/to/json` to `md2pdf`\n\n## Auto Generation of Table of Contents\n\n`md2pdf` can automatically generate a TOC where each item corresponds to a header in the doc and include it in the first page.\nTOC items can then be clicked to navigate to the relevant section (similar to HTML `\u003ca\u003e` anchors).\n\nTo make use of this feature, simply pass `--generate-toc` as an argument.\n\n## Quick start\n\n```\n$ cd cmd/md2pdf\n$ go run md2pdf.go -i test.md -o test.pdf\n```\n\nTo benefit from Syntax highlighting, invoke thusly:\n\n```\n$ go run md2pdf.go -i syn_test.md -s /path/to/syntax_files -o test.pdf\n```\n\nTo convert multiple MD files into a single PDF, use:\n```\n$ go run md2pdf.go -i /path/to/md/directory -o test.pdf\n```\n\nThis repo has the [gohighlight module](https://github.com/jessp01/gohighlight) configured as a submodule, so if you clone\nwith `--recursive`, you will have the `highlight` dir in its root. Alternatively, you may issue the following command to update an\nexisting clone:\n\n```sh\ngit submodule update --remote  --init\n```\n\n*Note 1: the `cmd` folder has an example for the syntax highlighting. \nSee the script `run_syntax_highlighting.sh`. This example assumes that\nthe folder with the syntax files is located at a relative location:\n`../../../jessp01/gohighlight/syntax_files`.*\n\n*Note 2: when annotating the code block to specify the language, the\nannotation name must match the syntax base filename.*\n\n### Additional options\n\n```sh\n  -author string\n    \tAuthor name; used if -footer is passed\n  -font-file string\n    \tpath to font file to use\n  -font-name string\n    \tFont name ID; e.g 'Helvetica-1251'\n  -generate-toc\n    \tAuto Generate Table of Contents (TOC)\n  -help\n    \tShow usage message\n  -i string\n    \tInput filename, dir consisting of .md|.markdown files or HTTP(s) URL; default is os.Stdin\n  -log-file string\n    \tPath to log file\n  -new-page-on-hr\n    \tInterpret HR as a new page; useful for presentations\n  -o string\n    \tOutput PDF filename; required\n  -orientation string\n    \t[portrait | landscape] (default \"portrait\")\n  -page-size string\n    \t[A3 | A4 | A5] (default \"A4\")\n  -s string\n    \tPath to github.com/jessp01/gohighlight/syntax_files\n  -theme string\n    \t[light | dark | /path/to/custom/theme.json] (default \"light\")\n  -title string\n    \tPresentation title\n  -unicode-encoding string\n    \te.g 'cp1251'\n  -version\n    \tPrint version and build info\n  -with-footer\n    \tPrint doc footer (\u003cauthor\u003e  \u003ctitle\u003e  \u003cpage number\u003e)\n```\n\nFor example, the below will:\n\n- Set the title to `My Grand Title`\n- Set `Random Bloke` as the author (used in the footer)\n- Set the dark theme\n- Start a new page when encountering an HR (`---`); useful for creating presentations\n- Print a footer (`author name, title, page number`)\n\n```sh\n$ go run md2pdf.go  -i /path/to/md \\\n    -o /path/to/pdf --title \"My Grand Title\" --author \"Random Bloke\" \\\n    --theme dark --new-page-on-hr --with-footer\n```\n\n## Using non-ASCII Glyphs/Fonts\n\nTo use a non-ASCII language, the PDF generator must be configured with `WithUnicodeTranslator`:\n\n```go\n// https://en.wikipedia.org/wiki/Windows-1251\npf := mdtopdf.NewPdfRenderer(\"\", \"\", *output, \"trace.log\", mdtopdf.WithUnicodeTranslator(\"cp1251\")) \n```\n\nIn addition, this package's `Styler` must be used to set the font to match what is configured with the PDF generator.\n\nA complete working example can be found for Russian in the `cmd` folder named\n`russian.go`.\n\nFor a full example, run:\n\n```sh\n$ go run md2pdf.go -i russian.md -o russian.pdf \\\n    --unicode-encoding cp1251 --font-file helvetica_1251.json --font-name Helvetica_1251\n```\n\n## Tests\n\nThe tests included in this repo (see the `testdata` folder) were taken from the BlackFriday package.\nWhile the tests may complete without errors, visual inspection of the created PDF is the\nonly way to determine if the tests *really* pass!\n\nThe tests create log files that trace the [gomarkdown](https://github.com/gomarkdown/markdown) parser\ncallbacks. This is a valuable debugging tool, showing each callback \nand the data provided while the AST is presented.\n\n## Limitations and Known Issues\n\n- It is common for Markdown to include HTML. HTML is treated as a \"code block\". *There is no attempt to convert raw HTML to PDF.*\n- Github-flavoured Markdown permits strikethrough using tildes. This is not supported by `fpdf` as a font style at present.\n- The markdown link title (which would show when converted to HTML as hover-over text) is not supported. The generated PDF will show the URL, but this is a function of the PDF viewer.\n- Definition lists are not supported\n- The following text features may be tweaked: font, size, spacing, style, fill colour, and text colour. These are exported and available via the `Styler` struct. Note that fill colour only works when using `CellFormat()`. This is the case for tables, code blocks, and backticked text.\n\n## Contributions\n\n- Set up and run pre-commit hooks:\n\n```sh\n# Install the needed GO packages:\ngo install github.com/go-critic/go-critic/cmd/gocritic@latest\ngo install golang.org/x/tools/cmd/goimports@latest\ngo install golang.org/x/lint/golint@latest\ngo install github.com/gordonklaus/ineffassign@latest\n\n# Install the `pre-commit` util:\npip install pre-commit\n\n# Generate `.git/hooks/pre-commit`:\npre-commit install\n```\n\nFollowing that, these tests will run every time you invoke `git commit`:\n```sh\ngo fmt...................................................................Passed\ngo imports...............................................................Passed\ngo vet...................................................................Passed\ngo lint..................................................................Passed\ngo-critic................................................................Passed\n```\n\n- Submit a pull request and include a succinct description of the feature or issue it addresses \n\n[license]: ./LICENSE\n[badge-license]: https://img.shields.io/github/license/solworktech/md2pdf.svg\n[go-docs-badge]: https://godoc.org/github.com/solworktech/md2pdf?status.svg\n[go-docs]: https://godoc.org/github.com/solworktech/md2pdf/v2\n[badge-build]: https://github.com/solworktech/md2pdf/actions/workflows/go.yml/badge.svg\n[build]: https://github.com/solworktech/md2pdf/actions/workflows/go.yml\n[go-report-card-badge]: https://goreportcard.com/badge/github.com/solworktech/md2pdf/v2\n[go-report-card]: https://goreportcard.com/report/github.com/solworktech/md2pdf/v2\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolworktech%2Fmd2pdf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsolworktech%2Fmd2pdf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsolworktech%2Fmd2pdf/lists"}