{"id":20821430,"url":"https://github.com/lolipopj/mdimg","last_synced_at":"2025-05-07T16:23:53.953Z","repository":{"id":57293566,"uuid":"459430911","full_name":"LolipopJ/mdimg","owner":"LolipopJ","description":"Convert Markdown or HTML to image!","archived":false,"fork":false,"pushed_at":"2023-04-18T16:54:56.000Z","size":1219,"stargazers_count":21,"open_issues_count":3,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-03T00:54:05.643Z","etag":null,"topics":["html","image","javascript","markdown","marked","nodejs","puppeteer"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/mdimg","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LolipopJ.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2022-02-15T04:47:18.000Z","updated_at":"2024-04-15T11:55:00.590Z","dependencies_parsed_at":"2024-04-15T12:08:45.916Z","dependency_job_id":null,"html_url":"https://github.com/LolipopJ/mdimg","commit_stats":{"total_commits":27,"total_committers":1,"mean_commits":27.0,"dds":0.0,"last_synced_commit":"96d5036365cc102521c1321d53f0714d850cb7d2"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LolipopJ%2Fmdimg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LolipopJ%2Fmdimg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LolipopJ%2Fmdimg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LolipopJ%2Fmdimg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LolipopJ","download_url":"https://codeload.github.com/LolipopJ/mdimg/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225096692,"owners_count":17420293,"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":["html","image","javascript","markdown","marked","nodejs","puppeteer"],"created_at":"2024-11-17T22:12:13.093Z","updated_at":"2024-11-17T22:12:13.686Z","avatar_url":"https://github.com/LolipopJ.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ca href=\"https://www.npmjs.com/package/mdimg\" target=\"_blank\"\u003e\u003cimg alt=\"lts-version\" src=\"https://img.shields.io/npm/v/mdimg.svg\"\u003e\u003c/a\u003e \u003ca href=\"https://www.npmjs.com/package/mdimg?activeTab=versions\" target=\"_blank\"\u003e\u003cimg alt=\"download-counts\" src=\"https://img.shields.io/npm/d18m/mdimg.svg\"\u003e\u003c/a\u003e \u003ca href=\"https://www.typescriptlang.org/\" target=\"_blank\"\u003e\u003cimg alt=\"language\" src=\"https://img.shields.io/badge/language-TypeScript-3178c6.svg\"\u003e\u003c/a\u003e\n\n# mdimg\n\nA tool that can be used to convert **Markdown** or **HTML** format text to an image.\n\n## How does it work?\n\nFirst, the script calls [marked](https://github.com/markedjs/marked) to parse Markdown into a HTML document. Next, use [Puppeteer](https://github.com/puppeteer/puppeteer) to start a headless browser and render the document with HTML and CSS templates. Finally, export our image through Puppeteer's [screenshot](https://pptr.dev/guides/screenshots/) API.\n\n## Preview\n\nRendering results:\n\n| MacOS                                                                           | Windows                                                                        | HTML Template | CSS Template | Notes                                             |\n| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------------- | ------------ | ------------------------------------------------- |\n| \u003cimg alt=\"default preview\" src=\"./docs/darwin/default.png\" height=\"150\"\u003e        | \u003cimg alt=\"default preview\" src=\"./docs/win32/default.png\" height=\"150\"\u003e        | `default`     | `default`    |\n| \u003cimg alt=\"empty preview\" src=\"./docs/darwin/empty.png\" height=\"150\"\u003e            | \u003cimg alt=\"empty preview\" src=\"./docs/win32/empty.png\" height=\"150\"\u003e            | `default`     | `empty`      | Only use base stylesheets                         |\n| \u003cimg alt=\"github preview\" src=\"./docs/darwin/github.png\" height=\"150\"\u003e          | \u003cimg alt=\"github preview\" src=\"./docs/win32/github.png\" height=\"150\"\u003e          | `default`     | `github`     |\n| \u003cimg alt=\"github dark preview\" src=\"./docs/darwin/githubDark.png\" height=\"150\"\u003e | \u003cimg alt=\"github dark preview\" src=\"./docs/win32/githubDark.png\" height=\"150\"\u003e | `default`     | `githubDark` | Should be used with `theme: \"dark\"`               |\n| \u003cimg alt=\"words preview\" src=\"./docs/darwin/words.png\" height=\"150\"\u003e            | \u003cimg alt=\"words preview\" src=\"./docs/win32/words.png\" height=\"150\"\u003e            | `words`       | `words`      | It is recommended to use with **plain text only** |\n\n## Requirements\n\nThis tool requires a LTS Node version (v18.0.0+).\n\nIf your node version is lower than 18, please use the legacy version [0.2.3](https://www.npmjs.com/package/mdimg/v/0.2.3).\n\n## Installation\n\nCLI:\n\n```bash\nnpm install -g mdimg\n```\n\nIn Node.js project:\n\n```bash\nnpm install mdimg\n```\n\n## Usage\n\n### CLI\n\nExample:\n\n```bash\nmdimg -i path/to/input.md -o path/to/output.png -w 600 --css github\n```\n\nmdimg will read text from `path/to/input.md` and convert it to an image file `path/to/output.png`.\n\nWhen using the command, you must specify either `-i` (input file, recommended) or `-t` (directly input text).\n\nWhen using `-t` to input Markdown text directly, escape characters will **not be available**. To fix this, for example, you should replace `\\n` with `\u003cbr\u003e`.\n\nYou can always call `mdimg -h` to get complete help.\n\n### In Node.js project\n\nImport mdimg to your project:\n\n```js\nimport { mdimg } from \"mdimg\";\n```\n\nConvert markdown file to an image:\n\n```js\nconst convertRes = await mdimg({\n  inputFilename: \"path/to/input.md\",\n  outputFilename: \"path/to/output.png\",\n  width: 600,\n  cssTemplate: \"github\",\n  theme: \"light\",\n  // or with dark theme\n  // cssTemplate: \"githubDark\",\n  // theme: \"dark\",\n});\n\nconsole.log(\n  `Convert to image successfully!\\nImage has been saved as \\`${convertRes.path}\\``,\n);\n```\n\nConvert markdown text to blob:\n\n```js\nconst convertRes = await mdimg({\n  inputText: \"# Hello world\",\n  encoding: \"blob\",\n});\n\n// import { writeFileSync } from \"fs\";\n// writeFileSync(\"path/to/output.png\", convertRes.data);\n```\n\nWhen using `mdimg()` method, you must specify either `inputFilename` (input file) or `inputText` (directly input text).\n\nHere are all available options:\n\n| Argument       | Type                             | Default                                      | Notes                                                                                                                                                                                                                 |\n| -------------- | -------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| inputText      | `String`                         | `undefined`                                  | Input Markdown or HTML text directly. This option **has no effect** if `inputFilename` is specified                                                                                                                   |\n| inputFilename  | `String`                         | `undefined`                                  | Read Markdown or HTML text from a file                                                                                                                                                                                |\n| outputFilename | `String`                         | `./mdimg_output/mdimg_${new Date()}.${type}` | Output binary image filename. Available file extensions: `jpeg`, `png`, `webp`. Available when `encoding` option is `binary`                                                                                          |\n| type           | `\"jpeg\" \\| \"png\" \\| \"webp\"`      | `png`                                        | File type of the image. Type will be inferred from `outputFilename` if specified                                                                                                                                      |\n| width          | `Number`                         | `800`                                        | Width in pixel of output image                                                                                                                                                                                        |\n| height         | `Number`                         | `100`                                        | Min-height in pixel of output image. No less than `100`                                                                                                                                                               |\n| encoding       | `\"base64\" \\| \"binary\" \\| \"blob\"` | `binary`                                     | Encode type of output image                                                                                                                                                                                           |\n| quality        | `Number`                         | `100`                                        | Quality of the image, between 0-100. **Not applicable** to `png` image                                                                                                                                                |\n| htmlText       | `String`                         | `undefined`                                  | HTML rendering text                                                                                                                                                                                                   |\n| cssText        | `String`                         | `undefined`                                  | CSS rendering text                                                                                                                                                                                                    |\n| htmlTemplate   | `String`                         | `default`                                    | HTML rendering template. Available presets can be found in [`template/html`](./template/html/). If ends with `.html`, the mdimg will try to read local file. This option **has no effect** if `htmlText` is specified |\n| cssTemplate    | `String`                         | `default`                                    | CSS rendering template. Available presets can be found in [`template/css`](./template/css/). If ends with `.css`, the mdimg will try to read local file. This option **has no effect** if `cssText` is specified      |\n| theme          | `light` \\| `dark`                | `light`                                      | Rendering color theme, will impact styles of code block and so on                                                                                                                                                     |\n| extensions     | `Boolean \\| IExtensionOptions`   | `true`                                       | Configurations for [extensions](#extensions)                                                                                                                                                                          |\n| log            | `Boolean`                        | `false`                                      | Print execution logs via stderr                                                                                                                                                                                       |\n| debug          | `Boolean`                        | `false`                                      | Whether to keep temporary HTML file after rendering                                                                                                                                                                   |\n| puppeteerProps | `LaunchOptions`                  | `undefined`                                  | [Launch options](https://pptr.dev/api/puppeteer.puppeteerlaunchoptions) of Puppeteer                                                                                                                                  |\n\nReturns: `Promise\u003cobject\u003e`\n\n| Key  | Value Type               | Notes                                                                                                                    |\n| ---- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |\n| data | `string` \\| `Uint8Array` | BASE64 encoded string (`encoding` is `base64`) or Uint8Array blob (`encoding` is `binary` or `blob`) of the output image |\n| path | `string`                 | Path of output image. Available when `encoding` is `binary`                                                              |\n| html | `string`                 | Rendered HTML document                                                                                                   |\n\n## Custom template\n\n\u003e **😍 Contribute to template presets via [pull requests](https://github.com/LolipopJ/mdimg/pulls) is welcomed!**\n\nTemplate presets are stored in the `template` directory.\n\nIf you execute the following command:\n\n```bash\nmdimg --html custom --css custom\n```\n\nOr in Node.js project:\n\n```js\nawait mdimg({\n  htmlTemplate: \"custom\",\n  cssTemplate: \"custom\",\n});\n```\n\nThe mdimg will read `template/html/custom.html` as HTML template and `template/css/custom.css` as CSS template in the mdimg directory to render the image.\n\n### HTML Template\n\nCreate a new `.html` file in `template/html` directory.\n\nThere is only one rule you need to follow: an element with id `mdimg-body` wrapping an element with class `markdown-body`.\n\nThe simplest example:\n\n```html\n\u003cdiv id=\"mdimg-body\"\u003e\n  \u003cdiv class=\"markdown-body\"\u003e\u003c/div\u003e\n\u003c/div\u003e\n```\n\nThe mdimg will put the parsed HTML content in the element which `class=\"markdown-body\"` (elements inside will be **replaced**), and finally generate the image for the whole element which `id=\"mdimg-body\"`.\n\n### CSS Template\n\nNothing to note, create a new `.css` file in `template/css` directory and then make your style!\n\nFor further development, it is recommended that write `.scss` or `.sass` files in the `template/scss` directory, and use the following command to generate CSS templates:\n\n```bash\n# Build .scss and .sass files\nyarn rollup:sass\n```\n\nCSS templates with the corresponding name will be generated in `template/css` directory.\n\n## Local Template\n\nTemplate presets may not often meet your needs. If you already know the specifications of [HTML template](#html-template) and [CSS template](#css-template), you can pass the template directly. There are two methods:\n\n1. Using local template file. Pass a local filepath with the **file extension `.html` and `.css`** through options `--html` and `--css` with CLI (`htmlTemplate` and `cssTemplate` with Node.js).\n2. Using template text. Pass template text through `--htmlText` and `--cssText` with CLI (`htmlText` and `cssText` with Node.js).\n\nCLI:\n\n```bash\n# use local file\nmdimg --html path/to/custom.html --css path/to/custom.css\n\n# use text directly\nmdimg --htmlText '\u003cdiv id=\"mdimg-body\"\u003e\u003cdiv class=\"markdown-body\"\u003e\u003c/div\u003e\u003c/div\u003e' --cssText '@import \"https://cdn.jsdelivr.net/npm/normalize.css/normalize.min.css\"; .markdown-body { padding: 6rem 4rem; }'\n```\n\nOr in Node.js project:\n\n```js\n// use local file\nawait mdimg({\n  htmlTemplate: \"path/to/custom.html\",\n  cssTemplate: \"path/to/custom.css\",\n});\n\n// use text directly\nawait mdimg({\n  htmlText: `\u003cdiv id=\"mdimg-body\"\u003e\n  \u003cdiv class=\"markdown-body\"\u003e\u003c/div\u003e\n\u003c/div\u003e`,\n  cssText: `@import \"https://cdn.jsdelivr.net/npm/normalize.css/normalize.min.css\";\n.markdown-body {\n  padding: 6rem 4rem;\n}`,\n});\n```\n\n## Extensions\n\nExtensions are default enabled. You can easily configuration them in Node.js:\n\n```ts\nawait mdimg({\n  extensions: false, // disable all extensions\n});\n\nawait mdimg({\n  extensions: {\n    highlightJs: false, // disable highlight.js\n    mathJax: {\n      // further configuration for MathJax\n      // ...\n    },\n    mermaid: true, // enable mermaid (by default)\n  },\n});\n```\n\nIn CLI, you can only enable or disable extensions globally:\n\n```bash\nmdimg --extensions false # disable all extensions\n```\n\n### Extended Syntaxes\n\nSome extended syntaxes, such as LaTeX, can't be parsed by pure marked correctly. To solve this problem, the mdimg introduces some third-party libraries to enhance rendering capabilities. Below are introduced libraries:\n\n#### [MathJax](https://github.com/mathjax/MathJax)\n\n\u003e MathJax is an open-source JavaScript display engine for **LaTeX**, **MathML**, and **AsciiMath** notation.\n\n⚠️ The single dollar sign `$` is **not enabled by default** to render inline LaTeX. Because It is used too frequently in normal text, so if you want to use it for math delimiters, you must specify it explicitly. In Node.js project:\n\n```ts\nawait mdimg({\n  extensions: {\n    mathJax: {\n      tex: {\n        inlineMath: [\n          [\"$\", \"$\"],\n          [\"\\\\(\", \"\\\\)\"],\n        ],\n      },\n    },\n  },\n});\n```\n\nCLI doesn't support to configuration extensions, so you need to override MathJax options in HTML template directly:\n\n```html\n\u003c!-- path/to/template.html --\u003e\n\u003cdiv id=\"mdimg-body\"\u003e\n  \u003cdiv class=\"markdown-body\"\u003e\u003c/div\u003e\n\u003c/div\u003e\n\n\u003cscript\u003e\n  MathJax = {\n    tex: {\n      inlineMath: [\n        [\"$\", \"$\"],\n        [\"\\\\(\", \"\\\\)\"],\n      ],\n    },\n  };\n\u003c/script\u003e\n```\n\n```bash\nmdimg --html path/to/template.html\n```\n\n⚠️ Due to the [parse behaviors](https://andrzejq.github.io/markdown-mathjax/editor/md-mhj.html) between marked and MathJax: \"\\\\\" before any ASCII punctuation character is backslash escape, so \"\\\\\\\\\" (or \"\\\\,\") should be written as \"\\\\\\\\\\\\\\\\\" (or \"\\\\\\\\,\"). You need to manually replace characters or **wrap the LaTeX code in a `\u003cdiv\u003e` block**. Example:\n\n```md\n\u003cdiv\u003e$$\nA_{m,n} =\n\\begin{pmatrix}\na_{1,1} \u0026 a_{1,2} \u0026 \\cdots \u0026 a_{1,n} \\\\\na_{2,1} \u0026 a_{2,2} \u0026 \\cdots \u0026 a_{2,n} \\\\\n\\vdots \u0026 \\vdots \u0026 \\ddots \u0026 \\vdots \\\\\na_{m,1} \u0026 a_{m,2} \u0026 \\cdots \u0026 a_{m,n}\n\\end{pmatrix}\n$$\u003c/div\u003e\n```\n\n#### [Mermaid](https://github.com/mermaid-js/mermaid)\n\n\u003e Mermaid is a JavaScript-based **diagramming** and **charting** tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams.\n\nSequence diagram example:\n\n````md\n```mermaid\nsequenceDiagram\n  Alice-\u003e\u003eBob: Hello Bob, how are you ?\n  Bob-\u003e\u003eAlice: Fine, thank you. And you?\n  create participant Carl\n  Alice-\u003e\u003eCarl: Hi Carl!\n  create actor D as Donald\n  Carl-\u003e\u003eD: Hi!\n  destroy Carl\n  Alice-xCarl: We are too many\n  destroy Bob\n  Bob-\u003e\u003eAlice: I agree\n```\n````\n\n### Other Extensions\n\n#### [Highlight.js](https://github.com/highlightjs/highlight.js)\n\n\u003e Highlight.js is a syntax highlighter.\n\n## Development\n\n```bash\ngit clone https://github.com/LolipopJ/mdimg.git\ncd mdimg\nyarn\n```\n\n### Lint\n\n```bash\n# Check lint rules\nyarn lint\n# Check lint rules and fix resolvable errors\nyarn lint:fix\n```\n\n### Build\n\n```bash\n# Build .js, .scss and .sass files\nyarn build\n```\n\n### Test\n\n```bash\n# Build productions before testing\nyarn build\n# Run test cases\nyarn test\n```\n\n## Inspired by\n\n- [md2img](https://github.com/363797271/md2img). Provided me the idea and a complete feasible solution.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flolipopj%2Fmdimg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flolipopj%2Fmdimg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flolipopj%2Fmdimg/lists"}