github.com/insionng/yougam@v0.0.0-20170714101924-2bc18d833463/public/libs/to-markdown/README.md (about)

     1  # to-markdown
     2  
     3  An HTML to Markdown converter written in JavaScript.
     4  
     5  The API is as follows:
     6  
     7  ```js
     8  toMarkdown(stringOfHTML, options);
     9  ```
    10  
    11  ## Installation
    12  
    13  ### Browser
    14  
    15  Download the compiled script located at `dist/to-markdown.js`.
    16  
    17  ```html
    18  <script src="PATH/TO/to-markdown.js"></script>
    19  <script>toMarkdown('<h1>Hello world!</h1>')</script>
    20  ```
    21  
    22  Or with **Bower**:
    23  
    24  ```sh
    25  $ bower install to-markdown
    26  ```
    27  
    28  ```html
    29  <script src="PATH/TO/bower_components/to-markdown/dist/to-markdown.js"></script>
    30  <script>toMarkdown('<h1>Hello world!</h1>')</script>
    31  ```
    32  
    33  ### Node.js
    34  
    35  Install the `to-markdown` module:
    36  
    37  ```sh
    38  $ npm install to-markdown
    39  ```
    40  
    41  Then you can use it like below:
    42  
    43  ```js
    44  var toMarkdown = require('to-markdown');
    45  toMarkdown('<h1>Hello world!</h1>');
    46  ```
    47  
    48  (Note it is no longer necessary to call `.toMarkdown` on the required module as of v1.)
    49  
    50  ## Options
    51  
    52  ### `converters` (array)
    53  
    54  to-markdown can be extended by passing in an array of converters to the options object:
    55  
    56  ```js
    57  toMarkdown(stringOfHTML, { converters: [converter1, converter2, …] });
    58  ```
    59  
    60  A converter object consists of a **filter**, and a **replacement**. This example from the source replaces `code` elements:
    61  
    62  ```js
    63  {
    64    filter: 'code',
    65    replacement: function(content) {
    66      return '`' + content + '`';
    67    }
    68  }
    69  ```
    70  
    71  #### `filter` (string|array|function)
    72  
    73  The filter property determines whether or not an element should be replaced. DOM nodes can be selected simply by filtering by tag name, with strings or with arrays of strings:
    74  
    75   * `filter: 'p'` will select `p` elements
    76   * `filter: ['em', 'i']` will select `em` or `i` elements
    77  
    78  Alternatively, 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 its only argument. For example, the following will match any `span` element with an `italic` font style:
    79  
    80  ```js
    81  filter: function (node) {
    82    return node.nodeName === 'SPAN' && /italic/i.test(node.style.fontStyle);
    83  }
    84  ```
    85  
    86  #### `replacement` (function)
    87  
    88  The 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, as well as the node itself (used in more complex conversions). It is called in the context of `toMarkdown`, and therefore has access to the methods detailed below.
    89  
    90  The following converter replaces heading elements (`h1`-`h6`):
    91  
    92  ```js
    93  {
    94    filter: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'],
    95  
    96    replacement: function(innerHTML, node) {
    97      var hLevel = node.tagName.charAt(1);
    98      var hPrefix = '';
    99      for(var i = 0; i < hLevel; i++) {
   100        hPrefix += '#';
   101      }
   102      return '\n' + hPrefix + ' ' + innerHTML + '\n\n';
   103    }
   104  }
   105  ```
   106  
   107  ### `gfm` (boolean)
   108  
   109  to-markdown has beta support for GitHub flavored markdown (GFM). Set the `gfm` option to true:
   110  
   111  ```js
   112  toMarkdown('<del>Hello world!</del>', { gfm: true });
   113  ```
   114  
   115  ## Methods
   116  
   117  The following methods can be called on the `toMarkdown` object.
   118  
   119  ### `isBlock(node)`
   120  
   121  Returns `true`/`false` depending on whether the element is block level.
   122  
   123  ### `isVoid(node)`
   124  
   125  Returns `true`/`false` depending on whether the element is [void](http://www.w3.org/TR/html-markup/syntax.html#syntax-elements).
   126  
   127  ### `trim(string)`
   128  
   129  Returns the string with leading and trailing whitespace removed.
   130  
   131  ### `outer(node)`
   132  
   133  Returns the content of the node along with the element itself.
   134  
   135  ## Development
   136  
   137  First make sure you have node.js/npm installed, then:
   138  
   139  ```sh
   140  $ npm install --dev
   141  $ bower install --dev
   142  ```
   143  
   144  Automatically browserify the module when source files change by running:
   145  
   146  ```sh
   147  $ npm start
   148  ```
   149  
   150  ### Tests
   151  
   152  To run the tests in the browser, open `test/index.html`.
   153  
   154  To run in node.js:
   155  
   156  ```sh
   157  $ npm test
   158  ```
   159  
   160  ## Credits
   161  
   162  Thanks to all [contributors](https://github.com/domchristie/to-markdown/graphs/contributors). Also, thanks to [Alex Cornejo](https://github.com/acornejo) for advice and inspiration for the breadth-first search algorithm.
   163  
   164  ## Licence
   165  
   166  to-markdown is copyright &copy; 2011-15 [Dom Christie](http://domchristie.co.uk) and released under the MIT license.