You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.md 6.4KB

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