{"id":13869711,"url":"https://github.com/patrick-kidger/mkposters","last_synced_at":"2025-11-17T15:33:40.763Z","repository":{"id":39753390,"uuid":"461341104","full_name":"patrick-kidger/mkposters","owner":"patrick-kidger","description":"Make posters from Markdown files.","archived":false,"fork":false,"pushed_at":"2023-05-04T18:00:40.000Z","size":6431,"stargazers_count":345,"open_issues_count":2,"forks_count":22,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-29T04:03:48.205Z","etag":null,"topics":["markdown","material-design","poster","template","theme"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/patrick-kidger.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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},"funding":{"github":["patrick-kidger"]}},"created_at":"2022-02-19T23:47:32.000Z","updated_at":"2025-03-26T19:55:23.000Z","dependencies_parsed_at":"2024-01-16T07:37:19.643Z","dependency_job_id":null,"html_url":"https://github.com/patrick-kidger/mkposters","commit_stats":{"total_commits":41,"total_committers":4,"mean_commits":10.25,"dds":0.1707317073170732,"last_synced_commit":"651b21a33f814375ac408abbf3de957e15c19bf5"},"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick-kidger%2Fmkposters","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick-kidger%2Fmkposters/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick-kidger%2Fmkposters/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/patrick-kidger%2Fmkposters/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/patrick-kidger","download_url":"https://codeload.github.com/patrick-kidger/mkposters/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247289409,"owners_count":20914464,"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":["markdown","material-design","poster","template","theme"],"created_at":"2024-08-05T20:01:13.138Z","updated_at":"2025-11-17T15:33:40.724Z","avatar_url":"https://github.com/patrick-kidger.png","language":"Python","funding_links":["https://github.com/sponsors/patrick-kidger"],"categories":["Python"],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eMkPosters\u003c/h1\u003e\n\nCreate posters using Markdown. Supports icons, admonitions, and LaTeX mathematics.\n\nAt the moment it is restricted to the specific layout of two-columns-with-banner-at-the-top, as that's what I tend to use. (Pull requests are welcome if you want to make this tool more general.) The poster can be either portrait or landscape.\n\nThe library operates by parsing your Markdown into HTML, styling it with CSS, and then opening a webpage that you can export to PDF.\n\n## Example\n\n\u003cimg style=\"width: 100%;\" src=\"https://raw.githubusercontent.com/patrick-kidger/mkposters/main/imgs/diffrax.png\" alt=\"Example poster\"\u003e\n\nThe \"source code\" for this example is [here](https://github.com/patrick-kidger/mkposters/tree/main/examples/diffrax).\n\n## Assumptions\n\nAssumes you have:\n- Linux (WSL is fine) or macOS\n- Firefox\n- Python\n\nCompatibility with other operating systems is probably possible by switching out the version of Dart Sass being used internally.  \nCompatibility with other browsers is unlikely.\n\nYou'll need to be relatively familiar with HTML and (S)CSS to make best use of MkPosters.\n\n## Installation\n\n```\npip install mkposters\n```\n\n## Usage instructions\n\n1. Create the appropriate directory structure\n\n```\nfoo/\n    poster.md\n    style.{css,scss} (optional)\n    ...any other assets e.g. images...\n```\n\n2. Lay out your poster\n\n`poster.md` should be formatted in three sections, with a literal \"`--split--`\" between each section.\n\n```\n...whatever you want in the banner at the top...\n\n--split--\n\n...whatever you want in the left column...\n\n--split--\n\n...whatever you want in the right column...\n```\n\n3. Build poster\n\nRun from the directory containing `foo`:\n```\npython -m mkposters foo\n```\n\nThe first time you do this, MkPosters will attempt to detect your system architecture and install the appropriate version of `dart-sass`. This was tested working on both an Apple M1 and an Ubuntu x86_64 machine.\n\nThis will also automatically watch the `foo` directory for any updates, and rebuild if necessary.\n\n4. View poster\n\nNow open Firefox (*not* Chrome etc.) and navigate to `localhost:8000`.\n\nWhat you see will be based on the size of your current browser window and may differ from the PDF version. So next hit `Control-P` and select \"Save to PDF\". What you see in the print preview is what you'll actually end up with!\n\nMake all your edits until you're happy with the result. Now let's save the result to PDF.\n\n5. Save to PDF\n\nSaving to PDF can be quite finickity, and in general depends on choice of browser etc. (For what it's worth the following is tested using Firefox on Windows 10 with `mkposters` running on Ubuntu 20.04 on WSL2.)\n\nIn the print dialog window we opened above:\n- Destination: \"Save to PDF\". **Do not use \"Microsoft Print to PDF\".**\n- Orientation: (portrait or landscape, as desired)\n- Pages: Custom: 1\n- Paper size: (whatever is desired; current styling works best on paper roughly A4 sized)\n- Margins: None\n- Options: uncheck \"Print headers and footers\"\n\n**Once again, make sure you're using Firefox.** Using other browsers (e.g. Chrome) or other PDF exporters (e.g. WeasyPrint) can introduce a variety of issues, such as saving text as images (which are unselectable in the PDF, and appear slightly pixelated), missing parts of the styling, or having faded colours (looking at you, Chrome).\n\n## Functionality\n\nMkPosters comes with a few extra pieces of functionality built in.\n\n#### Icons\n\nRecalling that Markdown can embed HTML, then icons can be embedded via e.g.\n```html\n\u003cimg style=\"height: 20pt; width: 20pt\" src=\"icons/fontawesome/brands/github.svg\"\u003e\n```\nwhere the list of available icons is [here](https://github.com/patrick-kidger/mkposters/tree/main/mkposters/third_party/icons).\n\n#### Mathematics\n\nYou can use LaTeX-formatted mathematics. This is done via\n\n```\n\\\\(inline math\\\\)\n\\\\[display math\\\\]\n```\n\nNote the double backslash.\n\n#### Admonitions\n\nAdmonitions can be added using the syntax\n\n```markdown\n!!! admonition_type \"Your title here\"\n\n    Your text here\n```\n\nwhere `admonition_type` is any of [these](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types) types, e.g. `info`, `tip`, etc.\n\n#### Custom (S)CSS styling\n\nIf you want to style your poster in a custom way, then you can include a `style.css` or `style.scss` file in your poster directory.\n\n#### HTML\n\nThe Markdown format allows you use arbitrary HTML inside of it.\n\n- The banner section often contains information (titles, authors, logos, URLs etc.) laid out in complicated ways. Directly writing HTML with embedded `style` attributes is simplest here. [See the start of this example.](https://raw.githubusercontent.com/patrick-kidger/mkposters/main/examples/diffrax/poster.md)\n- HTML can be (ab)used to modify spacing like so. (Analogous to those little `\\vspace`s you definitely never use in LaTeX documents.) In this example we move the content up by 10 points.\n```\n\u003cdiv style=\"margin-top: -10pt;\"\u003e\n...your content here...\n\u003c/div\u003e\n```\n\n## Future plans?\n\nIt'd be nice to support:\n- Other poster layouts, e.g. multiple columns;\n- Optionally automatically generating the PDF. (Practically speaking probably by automating the Firefox interaction through Selenium.)\n- Reducing package size by not including all of the `mkposters/third_party/icons` directory by default?\n\nPull requests welcome! See [CONTRIBUTING.md](https://github.com/patrick-kidger/mkposters/blob/main/CONTRIBUTING.md).\n\n## Similar tools\n\nThese all support some kind of conversion Markdown -\u003e something.\n- For documentation: [MkDocs](https://github.com/mkdocs/mkdocs/) with [mkdocs-material](https://github.com/squidfunk/mkdocs-material/).\n- For presentations: [reveal.js](https://github.com/hakimel/reveal.js)\n- For static sites: [Hugo](https://github.com/gohugoio/hugo) or [Jekyll](https://github.com/jekyll/jekyll)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrick-kidger%2Fmkposters","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpatrick-kidger%2Fmkposters","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpatrick-kidger%2Fmkposters/lists"}