{"id":22825362,"url":"https://github.com/crabdancing/pandoc-emojis-filter","last_synced_at":"2026-01-07T23:40:02.034Z","repository":{"id":253190756,"uuid":"842759280","full_name":"crabdancing/pandoc-emojis-filter","owner":"crabdancing","description":"A fork of pandoc-emojis-filter with Nix reproducibility","archived":false,"fork":false,"pushed_at":"2024-08-15T03:20:27.000Z","size":536,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-02-06T05:32:55.500Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TeX","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/crabdancing.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}},"created_at":"2024-08-15T02:49:57.000Z","updated_at":"2024-08-15T03:20:30.000Z","dependencies_parsed_at":"2024-08-15T04:03:00.583Z","dependency_job_id":null,"html_url":"https://github.com/crabdancing/pandoc-emojis-filter","commit_stats":null,"previous_names":["crabdancing/pandoc-emojis-filter"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crabdancing%2Fpandoc-emojis-filter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crabdancing%2Fpandoc-emojis-filter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crabdancing%2Fpandoc-emojis-filter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/crabdancing%2Fpandoc-emojis-filter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/crabdancing","download_url":"https://codeload.github.com/crabdancing/pandoc-emojis-filter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246397387,"owners_count":20770544,"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":[],"created_at":"2024-12-12T17:10:29.708Z","updated_at":"2026-01-07T23:40:01.982Z","avatar_url":"https://github.com/crabdancing.png","language":"TeX","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Converting MD containing emojis to PDF\n\nMarkdown to PDF conversion is quite easy using `pandoc`.\nThe real problem arises when trying to use unicode emojis.\nThese emojis are becoming a real standard right now,\nand they are also useful, since not only faces and hands\nare represented, but also, as one can see below, they\ncan represent common concepts such as packages, folders\nand files.\n\nHowever useful it is, it's quite difficult to convert\na markdown file containing emoji characters. You must\nsetup special fonts, overcome lack of support by the\nlatex engines, only to have black-and-white emojis.\n\nThe Pandoc Emoji Filter present in this repository solves\nall of these problems: it provides colored emojis by using\nknown emoji SVG repositories such as `twemoji` and `noto-emoji`.\nSome TeX knowledge might be useful though, since there is\na `template.tex` file needed to insert SVG images in some\ncontexts, such as code blocks.\n\n## Features\n\n- Emojis can be used in normal text, like this :apple:, or like the following:\n\n    📦package \\\n    ┣ 📂dir1 \\\n    ┃ ┗ 📂subdir \\\n    ┗ 📜file1\n\n- Codeblocks and Code can be used, like in `📂dir1`, or the following code block:\n\n    - even if it is inside a subitem\n\n          📦package\n          ┣ 📂dir1\n          ┃ ┗ 📂subdir\n          ┗ 📜file1\n\n    This requires some messing with latex code, because some packages\n    must be used. Specifically in this case, `fvextra` provides a\n    `Verbatim` environment that allows the inclusion of inner commands,\n    needed to display the image of the emoji. Thats why a `template.tex`\n    must be provided to Pandoc.\n\n- Literal emojis like `:name:` are not converted by this filter... but Pandoc can handle this.\n    Use `--from markdown+emoji` or `--from gfm`, and also the Pandoc Emoji Filter to get\n    these converted to PDF.\n\n    :smile: :airplane:\n\n    See [Non-pandoc extensions - Pandoc manual](https://pandoc.org/MANUAL.html#non-pandoc-extensions)\n\n## Limitations\n\n- Pre/Code tags are ignored by Pandoc when converting to PDF.\n    This filter is not supposed to do anything about this,\n    so I won't be doing anything here about it.\n\n    The following code block uses `\u003cpre\u003e...\u003c/pre\u003e` tags.\n    They will not be rendered in the PDF, but are visible in the\n    markdown visualization.\n\n    \u003cpre\u003e\n    📦package \\\n    ┣ 📂dir1 \\\n    ┃ ┗ 📂subdir \\\n    ┗ 📜file1\n    \u003c/pre\u003e\n\n    There should be a code block above... if you are looking at the [example.pdf](example.pdf),\n    you'll see nothing above.\n\n## Compiling a PDF from this `readme.md` file\n\nIn this project, I experimented with multiple ways to\ndo what I wanted. First, I tried with Javascript emoji\nconverter + Python Pandoc filter. Then, I discovered\nthat Pandoc filters could be made in Javascript,\nusing NodeJs, and made a completely JS solution.\n\nUse the NodeJS solution instead of the Python as\nit is the one I am currently developing more actively.\n\n## Javascript + Python filter\n\n    node app.js\n    pandoc --template=\"template.tex\" -o out.pdf output.md \\\n        --filter=svg_filter.py\n\n## Javascript only filter via NodeJs\n\nFirst, install JS script dependencies using npm:\n\n    npm install\n\nThen, run `pandoc` passing in the filter file name:\n\n    pandoc --template=\"template.tex\" -o out.pdf readme.md \\\n        --filter=emoji_filter.js\n\nPassing parameters:\n\n    pandoc --template=\"template.tex\" -o out.pdf readme.md \\\n        --filter=emoji_filter.js -M __debug=1 -M emoji=twemoji\n\nDebugging using VSCode:\n\n    pandoc --template=\"template.tex\" -o out.pdf readme.md \\\n        --filter=emoji_filter.js -M __debug=1\n\nThen, in VSCode, attach to Node process... the JS filter code will be waiting,\nand will only continue execution after the debugger is attached. If you don't attach\nthe debugger, then it will stall in an infinite loop.\n\n## Example: compiling this `readme.md`\n\nThis `readme.md` file was compiled using the following command:\n\n    pandoc --template=\"template.tex\" -o example.pdf readme.md \\\n        --filter=emoji_filter.js -M emoji=noto-emoji --from gfm\n\nThis is the resulting PDF: [example.pdf](example.pdf)\n\nYou can also run `create-example.sh`.\n\n## Filter parameters\n\nParameters are passed to the filter in the form of metadata.\nPandoc receives metadata using the `--metadata` or `-M` keywords.\nAlso, metadata can be specified inside markdown files, or YAML\nfiles via `--metadata-file`. See [Pandoc's manual - Metadata Blocks](https://pandoc.org/MANUAL.html#metadata-blocks)\nfor more info.\n\n### __debug\n\nThis is used to debug the filter using NodeJS inspector.\nVSCode can debug NodeJS instances, even the ones that started\nwithout debug parameters, via `SIGUSR1` signal.\n\nThe problem the this flag solves it that the filter\nexecution must wait for the debugger to be attached,\notherwise it finished before the user has the opportunity\nto debug the code.\n\nUsage: pass `-M __debug=1` to pandoc along with other params.\n\n### emoji\n\nThis is used to select the emoji source.\nAt this moment only two sources are available:\n\n- `twemoji`: [Twemoji by Twitter](https://twemoji.twitter.com/)\n- `noto-emoji`: [Noto Color Emoji by Google](https://www.google.com/get/noto/help/emoji/)\n\nUsage: pass `-M emoji=noto-emoji` or `-M emoji=twemoji` to pandoc along with other params.\n\nSee [Emojipedia](https://emojipedia.org/) for a list of emojis.\n\n## Changing emoji cache directory\n\nJust set the environment variable `SVG_FILTER_CACHE_DIR`.\n\nYou may need to use `declare -x SVG_FILTER_CACHE_DIR` in your script,\nso that the filter can see the environment variable.\n\n## References\n\n- [Full Emoji List - unicode.org](https://unicode.org/emoji/charts/full-emoji-list.html)\n- [Emojipedia](https://emojipedia.org/microsoft/)\n- VSCode extension: [file-tree-generator](https://marketplace.visualstudio.com/items?itemName=Shinotatwu-DS.file-tree-generator)\n- https://github.com/googlefonts/noto-emoji\n- `\\usepackage{pmboxdraw}`: this is used to draw file-structure lines\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrabdancing%2Fpandoc-emojis-filter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcrabdancing%2Fpandoc-emojis-filter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcrabdancing%2Fpandoc-emojis-filter/lists"}