1# mdurl 2 3[![Build Status](https://img.shields.io/travis/markdown-it/mdurl/master.svg?style=flat)](https://travis-ci.org/markdown-it/mdurl) 4[![NPM version](https://img.shields.io/npm/v/mdurl.svg?style=flat)](https://www.npmjs.org/package/mdurl) 5 6> URL utilities for [markdown-it](https://github.com/markdown-it/markdown-it) parser. 7 8 9## API 10 11### .encode(str [, exclude, keepEncoded]) -> String 12 13Percent-encode a string, avoiding double encoding. Don't touch `/a-zA-Z0-9/` + 14excluded chars + `/%[a-fA-F0-9]{2}/` (if not disabled). Broken surrorates are 15replaced with `U+FFFD`. 16 17Params: 18 19- __str__ - input string. 20- __exclude__ - optional, `;/?:@&=+$,-_.!~*'()#`. Additional chars to keep intact 21 (except `/a-zA-Z0-9/`). 22- __keepEncoded__ - optional, `true`. By default it skips already encoded sequences 23 (`/%[a-fA-F0-9]{2}/`). If set to `false`, `%` will be encoded. 24 25 26### encode.defaultChars, encode.componentChars 27 28You can use these constants as second argument to `encode` function. 29 30 - `encode.defaultChars` is the same exclude set as in the standard `encodeURI()` function 31 - `encode.componentChars` is the same exclude set as in the `encodeURIComponent()` function 32 33For example, `encode('something', encode.componentChars, true)` is roughly the equivalent of 34the `encodeURIComponent()` function (except `encode()` doesn't throw). 35 36 37### .decode(str [, exclude]) -> String 38 39Decode percent-encoded string. Invalid percent-encoded sequences (e.g. `%2G`) 40are left as is. Invalid UTF-8 characters are replaced with `U+FFFD`. 41 42 43Params: 44 45- __str__ - input string. 46- __exclude__ - set of characters to leave encoded, optional, `;/?:@&=+$,#`. 47 48 49### decode.defaultChars, decode.componentChars 50 51You can use these constants as second argument to `decode` function. 52 53 - `decode.defaultChars` is the same exclude set as in the standard `decodeURI()` function 54 - `decode.componentChars` is the same exclude set as in the `decodeURIComponent()` function 55 56For example, `decode('something', decode.defaultChars)` has the same behavior as 57`decodeURI('something')` on a correctly encoded input. 58 59 60### .parse(url, slashesDenoteHost) -> urlObs 61 62Parse url string. Similar to node's [url.parse](http://nodejs.org/api/url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost), but without any 63normalizations and query string parse. 64 65 - __url__ - input url (string) 66 - __slashesDenoteHost__ - if url starts with `//`, expect a hostname after it. Optional, `false`. 67 68Result (hash): 69 70- protocol 71- slashes 72- auth 73- port 74- hostname 75- hash 76- search 77- pathname 78 79Difference with node's `url`: 80 811. No leading slash in paths, e.g. in `url.parse('http://foo?bar')` pathname is 82 ``, not `/` 832. Backslashes are not replaced with slashes, so `http:\\example.org\` is 84 treated like a relative path 853. Trailing colon is treated like a part of the path, i.e. in 86 `http://example.org:foo` pathname is `:foo` 874. Nothing is URL-encoded in the resulting object, (in joyent/node some chars 88 in auth and paths are encoded) 895. `url.parse()` does not have `parseQueryString` argument 906. Removed extraneous result properties: `host`, `path`, `query`, etc., 91 which can be constructed using other parts of the url. 92 93 94### .format(urlObject) 95 96Format an object previously obtained with `.parse()` function. Similar to node's 97[url.format](http://nodejs.org/api/url.html#url_url_format_urlobj). 98 99 100## License 101 102[MIT](https://github.com/markdown-it/mdurl/blob/master/LICENSE) 103