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.

What's different about 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.

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:

<table>
  <thead>
    <tr>
      <th>Heading 1</th>
      <th>Heading 2</th>
      <th>Heading 3</th>
      <th>Heading 4</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Table cell</td>
      <td>Table cell</td>
      <td>Table cell</td>
      <td>Table cell</td>
    </tr>
    <tr>
      <td>Table cell</td>
      <td>Table cell</td>
      <td>Table cell</td>
      <td>Table cell</td>
    </tr>
  </tbody>
</table>

Would render to the following markdown:

| Heading 1 | Heading 2 | Heading 3 | Heading 4 | 
| --- | --- | --- | --- | 
| Table cell | Table cell | Table cell | Table cell | 
| Table cell | Table cell | Table cell | Table cell | 

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
85	jonschlinkert
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.

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

Install dev dependencies:

$ 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.4.2, on February 08, 2017.