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.
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!
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
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><tbody></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.
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 breakdance
- For maximum discoverability, plugin developers should use the keyword
breakdanceon packages which modify or add to the functionality of Breakdance when distributing through npm or similar delivery mechanisms.
- 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
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.
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
- CLI was externalized to [breakdance-cli]
2.0.0 - 2017-04-25
<b>: now renders as
**bold**, same as
<i>: now renders as
_italics_, same as
1.1.0 - 2017-04-21
<code>: improvements to whitespace handling
<code>: no longer renders empty tags
<p>: normalize Unicode
U+00A0non-breaking spaces to "normal" Unicode
U+0020spaces. Non-breaking spaces are useful in HTML, but cause flow problems in markdown.
- documentation for
options.trailingWhitespace, all previously undocumented options. See breakdance's options
1.0.0 - 2017-03-12
- Adds support for
<base>, closes issue #3
- Changed the CLI command from
br. As a fallback, you can also use
breakdanceif there is a conflict. The CLI has not yet been documented, so hopefully this doesn't cause any issues for anyone.
- An extra trailing newline was being added on
keepEmptyoption, to selective keep empty tags that are omitted by built-in
- Adds documentation for
utils.jsto breakdance-util, to allow plugin authors to use the same utilities as breakdance, for consistency.
- Better whitespace handling in
- Adds documentation for
(Changelog generated by helper-changelog)
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
This file was generated by verb-generate-readme, v0.5.0, on May 12, 2017.