breakdance

Breakdance is a node.js library for converting HTML to markdown. Highly pluggable, flexible and easy to use. It's time for your markup to get down.

Breakdance is a node.js library for converting HTML to markdown. You can use breakdance to:

• Migrate HTML blog posts to markdown
• Convert wiki pages to markdown
• Convert HTML documentation to markdown
• Convert HTML presentations or slide decks to markdown
• Convert busy web pages into readable markdown documents.

Visit breakdance.io for detailed documentation, examples, recipes, and advice on authoring and finding plugins.

Why should I use breakdance?

Breakdance uses cheerio to parse HTML, and snapdragon for rendering, which provides granular control over the entire conversion process in a way that is easy to understand, reason about, and customize. If you see something you don't like, it's easy to change!

Generates well-formatted markdown

• Comprehensive HTML tag coverage.
• Granular control over every HTML element and attributes
• Even converts HTML tables to markdown!

Extremely pluggable

Every part of the conversion is customizable:

• options are available for customizing output of any HTML tag if you don't like the defaults
• plugins are easy to write if you'd like to share your customizations with the world

HTML-to-markdown example

Tables

The following HTML table from bootstrap's docs:

<h2 id=tables-hover-rows>Hover rows</h2>
<p>Add <code>.table-hover</code> to enable a hover state on table rows within a <code>&lt;tbody&gt;</code>.</p>
<div class=bs-example data-example-id=hoverable-table>
  <table class="table table-hover">
    <thead>
      <tr>
        <th>#</th>
        <th>First Name</th>
        <th>Last Name</th>
        <th>Username</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <th scope=row>1</th>
        <td>Mark</td>
        <td>Otto</td>
        <td>@mdo</td>
      </tr>
      <tr>
        <th scope=row>2</th>
        <td>Jacob</td>
        <td>Thornton</td>
        <td>@fat</td>
      </tr>
      <tr>
        <th scope=row>3</th>
        <td>Larry</td>
        <td>the Bird</td>
        <td>@twitter</td>
      </tr>
    </tbody>
  </table>
</div>

Would render to the following markdown:

## Hover rows

Add `.table-hover` to enable a hover state on table rows within a `<tbody>`.

| # | First Name | Last Name | Username |
| --- | --- | --- | --- |
| 1 | Mark | Otto | @mdo |
| 2 | Jacob | Thornton | @fat |
| 3 | Larry | the Bird | @twitter |

See the documentation for more examples.

About

Community

Get updates on Breakdance's development and chat with the project maintainers and community members.

• Follow @breakdancejs on Twitter.
• Join the conversation on Gitter
• Implementation help may be found on Stack Overflow (please use the tag breakdancebreakdance).
• For maximum discoverability, plugin developers should use the keyword breakdance on packages which modify or add to the functionality of Breakdance when distributing through npm or similar delivery mechanisms.

Related projects

• breakdance-checklist: Plugin that adds checklist rendering support to breakdance, similar to task lists in github-flavored-markdown. | homepage
• breakdance-reflinks: Breakdance plugin that aggregates the urls from hrefs and src attributes at the bottom of… more | homepage
• breakdance-util: Utility functions for breakdance plugins. | homepage

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, please create an issue.

Please read the contributing guide for advice on opening issues, pull requests, and coding standards.

Contributors

Commits	Contributor
118	jonschlinkert
3	doowb
1	davidbgk

Release history

Changelog entries are classified using the following labels from keep-a-changelog:

• added: for new features
• changed: for changes in existing functionality
• deprecated: for once-stable features removed in upcoming releases
• removed: for deprecated features removed in this release
• fixed: for any bug fixes

Custom labels used in this changelog:

• dependencies: bumps dependencies
• housekeeping: code re-organization, minor edits, or other changes that don't fit in one of the other categories.

3.0.0 - 2017-05-12

Removed

• CLI was externalized to [breakdance-cli][]

2.0.0 - 2017-04-25

Changed

• <b>: now renders as **bold**, same as <strong> tags
• <i>: now renders as _italics_, same as <em> tags

1.1.0 - 2017-04-21

Fixed

• <code>: improvements to whitespace handling
• <code>: no longer renders empty tags
• <p>: normalize Unicode U+00A0 non-breaking spaces to "normal" Unicode U+0020 spaces. Non-breaking spaces are useful in HTML, but cause flow problems in markdown.

Added

• documentation for options.comments, options.unsmarty, options.trailingWhitespace, all previously undocumented options. See breakdance.io/options

1.0.0 - 2017-03-12

Added

• Adds support for <base>, closes issue #3

Changed

• Changed the CLI command from tomd to either br. As a fallback, you can also use breakdance if there is a conflict. The CLI has not yet been documented, so hopefully this doesn't cause any issues for anyone.

0.1.5

Fixed

• An extra trailing newline was being added on <code> tags

Added

• Adds keepEmpty option, to selective keep empty tags that are omitted by built-in omitEmpty tags
• Adds documentation for omit, pick and omitEmpty and keepEmpty options

Changed

• Externalized utils.js to breakdance-util, to allow plugin authors to use the same utilities as breakdance, for consistency.

0.1.4

Fixed

• Better whitespace handling in table, a and dl tags

Added

• Adds documentation for url option

[0.1.0]

First release.

(Changelog generated by helper-changelog)

Running tests

Running and reviewing unit tests is a great way to get familiarized with a library and its API. You can install dependencies and run tests with the following command:

$ npm install && npm test

Author

Jon Schlinkert

• github/jonschlinkert
• twitter/jonschlinkert

License

Copyright © 2017, Jon Schlinkert. Released under the MIT license.

---

This file was generated by verb-generate-readme, v0.5.0, on May 12, 2017.