| [79a0317] | 1 | # relateurl [![NPM Version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Dependency Status][david-image]][david-url]
|
|---|
| 2 |
|
|---|
| 3 | > Minify URLs by converting them from absolute to relative.
|
|---|
| 4 |
|
|---|
| 5 | If you were to use this library on a website like `http://example.com/dir1/dir1-1/`, you would get results such as:
|
|---|
| 6 |
|
|---|
| 7 | | Before | After |
|
|---|
| 8 | | :------------------------------------------ | :----------------------------------- |
|
|---|
| 9 | | `http://example.com/dir1/dir1-2/index.html` | `../dir1-2/` |
|
|---|
| 10 | | `http://example.com/dir2/dir2-1/` | `/dir2/dir2-1/` |
|
|---|
| 11 | | `http://example.com/dir1/dir1-1/` | ` ` |
|
|---|
| 12 | | `https://example.com/dir1/dir1-1/` | `https://example.com/dir1/dir1-1/` |
|
|---|
| 13 | | `http://google.com:80/dir/` | `//google.com/dir/` |
|
|---|
| 14 | | `../../../../../../../../#anchor` | `/#anchor` |
|
|---|
| 15 |
|
|---|
| 16 | **All string parsing.** *No* directory browsing. It is thoroughly tested, very fast and lightweight with zero external dependencies.
|
|---|
| 17 |
|
|---|
| 18 | ## Getting Started
|
|---|
| 19 |
|
|---|
| 20 | This utility requires [Node.js](http://nodejs.org/) `>= 0.10`. To install, type this at the command line:
|
|---|
| 21 | ```
|
|---|
| 22 | npm install relateurl --save-dev
|
|---|
| 23 | ```
|
|---|
| 24 |
|
|---|
| 25 | ### Options
|
|---|
| 26 |
|
|---|
| 27 | #### options.defaultPorts
|
|---|
| 28 | Type: `Object`
|
|---|
| 29 | Default value: `{ftp:21, http:80, https:443}`
|
|---|
| 30 |
|
|---|
| 31 | Extend the list with any ports you need. Any URLs containing these default ports will have them removed. Example: `http://example.com:80/` will become `http://example.com/`.
|
|---|
| 32 |
|
|---|
| 33 | #### options.directoryIndexes
|
|---|
| 34 | Type: `Array`
|
|---|
| 35 | Default value: `["index.html"]`
|
|---|
| 36 |
|
|---|
| 37 | Extend the list with any resources you need. Works with [`options.removeDirectoryIndexes`](#options.removeDirectoryIndexes).
|
|---|
| 38 |
|
|---|
| 39 | #### options.ignore_www
|
|---|
| 40 | Type: `Boolean`
|
|---|
| 41 | Default value: `false`
|
|---|
| 42 |
|
|---|
| 43 | This will, for example, consider any domains containing `http://www.example.com/` to be related to any that contain `http://example.com/`.
|
|---|
| 44 |
|
|---|
| 45 | #### options.output
|
|---|
| 46 | Type: constant or `String`
|
|---|
| 47 | Choices: `RelateUrl.ABSOLUTE`,`RelateUrl.PATH_RELATIVE`,`RelateUrl.ROOT_RELATIVE`,`RelateUrl.SHORTEST`
|
|---|
| 48 | Choices: `"absolute"`,`"pathRelative"`,`"rootRelative"`,`"shortest"`
|
|---|
| 49 | Default value: `RelateUrl.SHORTEST`
|
|---|
| 50 |
|
|---|
| 51 | `RelateUrl.ABSOLUTE` will produce an absolute URL. Overrides [`options.schemeRelative`](#options.schemeRelative) with a value of `false`.
|
|---|
| 52 | `RelateUrl.PATH_RELATIVE` will produce something like `../child-of-parent/etc/`.
|
|---|
| 53 | `RelateUrl.ROOT_RELATIVE` will produce something like `/child-of-root/etc/`.
|
|---|
| 54 | `RelateUrl.SHORTEST` will choose whichever is shortest between root- and path-relative.
|
|---|
| 55 |
|
|---|
| 56 | #### options.rejectedSchemes
|
|---|
| 57 | Type: `Array`
|
|---|
| 58 | Default value: `["data","javascript","mailto"]`
|
|---|
| 59 |
|
|---|
| 60 | Extend the list with any additional schemes. Example: `javascript:something` will not be modified.
|
|---|
| 61 |
|
|---|
| 62 | #### options.removeAuth
|
|---|
| 63 | Type: `Boolean`
|
|---|
| 64 | Default value: `false`
|
|---|
| 65 |
|
|---|
| 66 | Remove user authentication information from the output URL.
|
|---|
| 67 |
|
|---|
| 68 | #### options.removeDirectoryIndexes
|
|---|
| 69 | Type: `Boolean`
|
|---|
| 70 | Default value: `true`
|
|---|
| 71 |
|
|---|
| 72 | Remove any resources that match any found in [`options.directoryIndexes`](#options.directoryIndexes).
|
|---|
| 73 |
|
|---|
| 74 | #### options.removeEmptyQueries
|
|---|
| 75 | Type: `Boolean`
|
|---|
| 76 | Default value: `false`
|
|---|
| 77 |
|
|---|
| 78 | Remove empty query variables. Example: `http://domain.com/?var1&var2=&var3=asdf` will become `http://domain.com/?var3=adsf`. This does not apply to unrelated URLs (with other protocols, auths, hosts and/or ports).
|
|---|
| 79 |
|
|---|
| 80 | #### options.removeRootTrailingSlash
|
|---|
| 81 | Type: `Boolean`
|
|---|
| 82 | Default value: `true`
|
|---|
| 83 |
|
|---|
| 84 | Remove trailing slashes from root paths. Example: `http://domain.com/?var` will become `http://domain.com?var` while `http://domain.com/dir/?var` will not be modified.
|
|---|
| 85 |
|
|---|
| 86 | #### options.schemeRelative
|
|---|
| 87 | Type: `Boolean`
|
|---|
| 88 | Default value: `true`
|
|---|
| 89 |
|
|---|
| 90 | Output URLs relative to the scheme. Example: `http://example.com/` will become `//example.com/`.
|
|---|
| 91 |
|
|---|
| 92 | #### options.site
|
|---|
| 93 | Type: `String`
|
|---|
| 94 | Default value: `undefined`
|
|---|
| 95 |
|
|---|
| 96 | An options-based version of the [`from`](#examples) argument. If both are specified, `from` takes priority.
|
|---|
| 97 |
|
|---|
| 98 | #### options.slashesDenoteHost
|
|---|
| 99 | Type: `Boolean`
|
|---|
| 100 | Default value: `true`
|
|---|
| 101 |
|
|---|
| 102 | Passed to Node's [`url.parse`](http://nodejs.org/api/url.html#url_url_parse_urlstr_parsequerystring_slashesdenotehost).
|
|---|
| 103 |
|
|---|
| 104 | ### Examples
|
|---|
| 105 | This library can be used as a [function for single-use](#single-instance) or as a [class for multiple conversions](#reusable-instances).
|
|---|
| 106 |
|
|---|
| 107 | Upon successful conversion, a `String` will be returned. If an issue is encountered while parsing `from`, an error will be thrown.
|
|---|
| 108 |
|
|---|
| 109 | #### Single Instance
|
|---|
| 110 | ```js
|
|---|
| 111 | var RelateUrl = require("relateurl");
|
|---|
| 112 |
|
|---|
| 113 | var result = RelateUrl.relate(from, to, options);
|
|---|
| 114 | ```
|
|---|
| 115 |
|
|---|
| 116 | #### Reusable Instances
|
|---|
| 117 | ```js
|
|---|
| 118 | var RelateUrl = require("relateurl");
|
|---|
| 119 |
|
|---|
| 120 | var instance = new RelateUrl(from, options);
|
|---|
| 121 |
|
|---|
| 122 | var result1 = instance.relate(to1);
|
|---|
| 123 | var result2 = instance.relate(to2, customOptions);
|
|---|
| 124 | var result3 = instance.relate(to3);
|
|---|
| 125 | ```
|
|---|
| 126 |
|
|---|
| 127 | ## FAQ
|
|---|
| 128 | 1. **Why bother writing/using this?**
|
|---|
| 129 | To aid in further minifying HTML, mainly for the purpose of faster page loads and SEO. It's been integrated into [HTMLMinifier](https://github.com/kangax/html-minifier).
|
|---|
| 130 |
|
|---|
| 131 | 2. **Why not just use Node's `url.parse`, `url.resolve` and `path.relative`?**
|
|---|
| 132 | `url.parse` *is* used, but `url.resolve` and `path.relative` are both slower and less powerful than this library.
|
|---|
| 133 |
|
|---|
| 134 |
|
|---|
| 135 | ## Release History
|
|---|
| 136 | * 0.2.7 Node v6 support
|
|---|
| 137 | * 0.2.6 minor enhancements
|
|---|
| 138 | * 0.2.5 added `options.removeRootTrailingSlash`
|
|---|
| 139 | * 0.2.4 added `options.site`
|
|---|
| 140 | * 0.2.3 added browserify npm-script
|
|---|
| 141 | * 0.2.2 removed task runner
|
|---|
| 142 | * 0.2.1 shorten resource- and query-relative URLs, test variations list with other site URLs
|
|---|
| 143 | * 0.2.0 code cleanup, `options.removeEmptyQueries=true` only applied to unrelated URLs
|
|---|
| 144 | * 0.1.0 initial release
|
|---|
| 145 |
|
|---|
| 146 |
|
|---|
| 147 | ## Roadmap
|
|---|
| 148 | * 0.2.8 check if queries are the same, regardless of param order
|
|---|
| 149 | * 0.2.8 possible [scheme exclusions](http://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml) such as `tel:`
|
|---|
| 150 | * 0.2.8 decipher and return invalid input (special cases) to complete test suite
|
|---|
| 151 | * 0.3.0 test `options.slashesDenoteHost=false`, add something like `options.externalDirectoryIndexes=[]` for external sites
|
|---|
| 152 |
|
|---|
| 153 |
|
|---|
| 154 | [npm-image]: https://img.shields.io/npm/v/relateurl.svg
|
|---|
| 155 | [npm-url]: https://npmjs.org/package/relateurl
|
|---|
| 156 | [travis-image]: https://img.shields.io/travis/stevenvachon/relateurl.svg
|
|---|
| 157 | [travis-url]: https://travis-ci.org/stevenvachon/relateurl
|
|---|
| 158 | [david-image]: https://img.shields.io/david/stevenvachon/relateurl.svg
|
|---|
| 159 | [david-url]: https://david-dm.org/stevenvachon/relateurl
|
|---|
