{"id":503460,"url":"https://domchristie.github.io/to-markdown","last_synced_at":"2025-08-11T11:32:12.168Z","repository":{"id":37380184,"uuid":"2630230","full_name":"mixmark-io/turndown","owner":"mixmark-io","description":"🛏 An HTML to Markdown converter written in JavaScript","archived":false,"fork":false,"pushed_at":"2024-07-30T02:22:34.000Z","size":4114,"stargazers_count":8827,"open_issues_count":131,"forks_count":880,"subscribers_count":123,"default_branch":"master","last_synced_at":"2024-10-29T16:58:11.414Z","etag":null,"topics":["browser","commonmark","gfm","html","html-to-markdown","javascript","markdown","node"],"latest_commit_sha":null,"homepage":"https://mixmark-io.github.io/turndown","language":"HTML","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/mixmark-io.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-10-23T10:35:39.000Z","updated_at":"2024-10-29T14:16:12.000Z","dependencies_parsed_at":"2024-04-15T18:10:34.982Z","dependency_job_id":"ca90668b-9eb0-4220-9e93-356e5a46c549","html_url":"https://github.com/mixmark-io/turndown","commit_stats":{"total_commits":371,"total_committers":32,"mean_commits":11.59375,"dds":0.2695417789757413,"last_synced_commit":"97e4535ca76bb2e70d9caa2aa4d4686956b06d44"},"previous_names":["domchristie/to-markdown","domchristie/turndown"],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixmark-io%2Fturndown","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixmark-io%2Fturndown/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixmark-io%2Fturndown/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mixmark-io%2Fturndown/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mixmark-io","download_url":"https://codeload.github.com/mixmark-io/turndown/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":229309032,"owners_count":18053039,"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":["browser","commonmark","gfm","html","html-to-markdown","javascript","markdown","node"],"created_at":"2024-01-09T02:01:02.184Z","updated_at":"2024-12-13T10:30:47.680Z","avatar_url":"https://github.com/mixmark-io.png","language":"HTML","funding_links":[],"categories":["Markdown Resources"],"sub_categories":["4. (optional) Preview your post"],"readme":"# Turndown\n\nConvert HTML into Markdown with JavaScript.\n\n## Project Updates\n* `to-markdown` has been renamed to Turndown. See the [migration guide](https://github.com/domchristie/to-markdown/wiki/Migrating-from-to-markdown-to-Turndown) for details.\n* Turndown repository has changed its URL to https://github.com/mixmark-io/turndown.\n\n## Installation\n\nnpm:\n\n```\nnpm install turndown\n```\n\nBrowser:\n\n```html\n\u003cscript src=\"https://unpkg.com/turndown/dist/turndown.js\"\u003e\u003c/script\u003e\n```\n\nFor usage with RequireJS, UMD versions are located in `lib/turndown.umd.js` (for Node.js) and `lib/turndown.browser.umd.js` for browser usage. These files are generated when the npm package is published. To generate them manually, clone this repo and run `npm run build`.\n\n## Usage\n\n```js\n// For Node.js\nvar TurndownService = require('turndown')\n\nvar turndownService = new TurndownService()\nvar markdown = turndownService.turndown('\u003ch1\u003eHello world!\u003c/h1\u003e')\n```\n\nTurndown also accepts DOM nodes as input (either element nodes, document nodes,  or document fragment nodes):\n\n```js\nvar markdown = turndownService.turndown(document.getElementById('content'))\n```\n\n## Options\n\nOptions can be passed in to the constructor on instantiation. For example:\n\n```js\nvar turndownService = new TurndownService({ option: 'value' })\n```\n\n| Option                | Valid values  | Default |\n| :-------------------- | :------------ | :------ |\n| `headingStyle`        | `setext` or `atx` | `setext`  |\n| `hr`                  | Any [Thematic break](http://spec.commonmark.org/0.27/#thematic-breaks) | `* * *` |\n| `bulletListMarker`    | `-`, `+`, or `*` | `*` |\n| `codeBlockStyle`      | `indented` or `fenced` | `indented` |\n| `fence`               | ` ``` ` or `~~~` | ` ``` ` |\n| `emDelimiter`         | `_` or `*` | `_` |\n| `strongDelimiter`     | `**` or `__` | `**` |\n| `linkStyle`           | `inlined` or `referenced` | `inlined` |\n| `linkReferenceStyle`  | `full`, `collapsed`, or `shortcut` | `full` |\n| `preformattedCode`    | `false` or [`true`](https://github.com/lucthev/collapse-whitespace/issues/16) | `false` |\n\n### Advanced Options\n\n| Option                | Valid values  | Default |\n| :-------------------- | :------------ | :------ |\n| `blankReplacement`    | rule replacement function | See **Special Rules** below |\n| `keepReplacement`     | rule replacement function | See **Special Rules** below |\n| `defaultReplacement`  | rule replacement function | See **Special Rules** below |\n\n## Methods\n\n### `addRule(key, rule)`\n\nThe `key` parameter is a unique name for the rule for easy reference. Example:\n\n```js\nturndownService.addRule('strikethrough', {\n  filter: ['del', 's', 'strike'],\n  replacement: function (content) {\n    return '~' + content + '~'\n  }\n})\n```\n\n`addRule` returns the `TurndownService` instance for chaining.\n\nSee **Extending with Rules** below.\n\n### `keep(filter)`\n\nDetermines which elements are to be kept and rendered as HTML. By default, Turndown does not keep any elements. The filter parameter works like a rule filter (see section on filters belows). Example:\n\n```js\nturndownService.keep(['del', 'ins'])\nturndownService.turndown('\u003cp\u003eHello \u003cdel\u003eworld\u003c/del\u003e\u003cins\u003eWorld\u003c/ins\u003e\u003c/p\u003e') // 'Hello \u003cdel\u003eworld\u003c/del\u003e\u003cins\u003eWorld\u003c/ins\u003e'\n```\n\nThis will render `\u003cdel\u003e` and `\u003cins\u003e` elements as HTML when converted.\n\n`keep` can be called multiple times, with the newly added keep filters taking precedence over older ones. Keep filters will be overridden by the standard CommonMark rules and any added rules. To keep elements that are normally handled by those rules, add a rule with the desired behaviour.\n\n`keep` returns the `TurndownService` instance for chaining.\n\n### `remove(filter)`\n\nDetermines which elements are to be removed altogether i.e. converted to an empty string. By default, Turndown does not remove any elements. The filter parameter works like a rule filter (see section on filters belows). Example:\n\n```js\nturndownService.remove('del')\nturndownService.turndown('\u003cp\u003eHello \u003cdel\u003eworld\u003c/del\u003e\u003cins\u003eWorld\u003c/ins\u003e\u003c/p\u003e') // 'Hello World'\n```\n\nThis will remove `\u003cdel\u003e` elements (and contents).\n\n`remove` can be called multiple times, with the newly added remove filters taking precedence over older ones. Remove filters will be overridden by the keep filters,  standard CommonMark rules, and any added rules. To remove elements that are normally handled by those rules, add a rule with the desired behaviour.\n\n`remove` returns the `TurndownService` instance for chaining.\n\n### `use(plugin|array)`\n\nUse a plugin, or an array of plugins. Example:\n\n```js\n// Import plugins from turndown-plugin-gfm\nvar turndownPluginGfm = require('turndown-plugin-gfm')\nvar gfm = turndownPluginGfm.gfm\nvar tables = turndownPluginGfm.tables\nvar strikethrough = turndownPluginGfm.strikethrough\n\n// Use the gfm plugin\nturndownService.use(gfm)\n\n// Use the table and strikethrough plugins only\nturndownService.use([tables, strikethrough])\n```\n\n`use` returns the `TurndownService` instance for chaining.\n\nSee **Plugins** below.\n\n## Extending with Rules\n\nTurndown can be extended by adding **rules**. A rule is a plain JavaScript object with `filter` and `replacement` properties. For example, the rule for converting `\u003cp\u003e` elements is as follows:\n\n```js\n{\n  filter: 'p',\n  replacement: function (content) {\n    return '\\n\\n' + content + '\\n\\n'\n  }\n}\n```\n\nThe filter selects `\u003cp\u003e` elements, and the replacement function returns the `\u003cp\u003e` contents separated by two new lines.\n\n### `filter` String|Array|Function\n\nThe filter property determines whether or not an element should be replaced with the rule's `replacement`. DOM nodes can be selected simply using a tag name or an array of tag names:\n\n * `filter: 'p'` will select `\u003cp\u003e` elements\n * `filter: ['em', 'i']` will select `\u003cem\u003e` or `\u003ci\u003e` elements\n\nThe tag names in the `filter` property are expected in lowercase, regardless of their form in the document.\n\nAlternatively, the filter can be a function that returns a boolean depending on whether a given node should be replaced. The function is passed a DOM node as well as the `TurndownService` options. For example, the following rule selects `\u003ca\u003e` elements (with an `href`) when the `linkStyle` option is `inlined`:\n\n```js\nfilter: function (node, options) {\n  return (\n    options.linkStyle === 'inlined' \u0026\u0026\n    node.nodeName === 'A' \u0026\u0026\n    node.getAttribute('href')\n  )\n}\n```\n\n### `replacement` Function\n\nThe replacement function determines how an element should be converted. It should return the Markdown string for a given node. The function is passed the node's content, the node itself, and the `TurndownService` options.\n\nThe following rule shows how `\u003cem\u003e` elements are converted:\n\n```js\nrules.emphasis = {\n  filter: ['em', 'i'],\n\n  replacement: function (content, node, options) {\n    return options.emDelimiter + content + options.emDelimiter\n  }\n}\n```\n\n### Special Rules\n\n**Blank rule** determines how to handle blank elements. It overrides every rule (even those added via `addRule`). A node is blank if it only contains whitespace, and it's not an `\u003ca\u003e`, `\u003ctd\u003e`,`\u003cth\u003e` or a void element. Its behaviour can be customised using the `blankReplacement` option.\n\n**Keep rules** determine how to handle the elements that should not be converted, i.e. rendered as HTML in the Markdown output. By default, no elements are kept. Block-level elements will be separated from surrounding content by blank lines. Its behaviour can be customised using the `keepReplacement` option.\n\n**Remove rules** determine which elements to remove altogether. By default, no elements are removed.\n\n**Default rule** handles nodes which are not recognised by any other rule. By default, it outputs the node's text content (separated  by blank lines if it is a block-level element). Its behaviour can be customised with the `defaultReplacement` option.\n\n### Rule Precedence\n\nTurndown iterates over the set of rules, and picks the first one that matches the `filter`. The following list describes the order of precedence:\n\n1. Blank rule\n2. Added rules (optional)\n3. Commonmark rules\n4. Keep rules\n5. Remove rules\n6. Default rule\n\n## Plugins\n\nThe plugin API provides a convenient way for developers to apply multiple extensions. A plugin is just a function that is called with the `TurndownService` instance.\n\n## Escaping Markdown Characters\n\nTurndown uses backslashes (`\\`) to escape Markdown characters in the HTML input. This ensures that these characters are not interpreted as Markdown when the output is compiled back to HTML. For example, the contents of `\u003ch1\u003e1. Hello world\u003c/h1\u003e` needs to be escaped to `1\\. Hello world`, otherwise it will be interpreted as a list item rather than a heading.\n\nTo avoid the complexity and the performance implications of parsing the content of every HTML element as Markdown, Turndown uses a group of regular expressions to escape potential Markdown syntax. As a result, the escaping rules can be quite aggressive.\n\n### Overriding `TurndownService.prototype.escape`\n\nIf you are confident in doing so, you may want to customise the escaping behaviour to suit your needs. This can be done by overriding `TurndownService.prototype.escape`. `escape` takes the text of each HTML element and should return a version with the Markdown characters escaped.\n\nNote: text in code elements is never passed to`escape`.\n\n## License\n\nturndown is copyright © 2017+ Dom Christie and released under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/domchristie.github.io%2Fto-markdown","html_url":"https://awesome.ecosyste.ms/projects/domchristie.github.io%2Fto-markdown","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/domchristie.github.io%2Fto-markdown/lists"}