README.md

   1 # hexo-nofollow
   2
   3 [![npm version](https://badge.fury.io/js/hexo-nofollow.svg)](https://www.npmjs.com/package/hexo-nofollow)
   4 [![Build Status](https://travis-ci.com/curbengh/hexo-nofollow.svg?branch=master)](https://travis-ci.com/curbengh/hexo-nofollow)
   5 [![NPM Dependencies](https://david-dm.org/curbengh/hexo-nofollow.svg)](https://david-dm.org/curbengh/hexo-nofollow)
   6 [![Known Vulnerabilities](https://snyk.io/test/npm/hexo-nofollow/badge.svg)](https://snyk.io/test/npm/hexo-nofollow)
   7 [![Greenkeeper badge](https://badges.greenkeeper.io/curbengh/hexo-nofollow.svg)](https://greenkeeper.io/)
   8
   9 > :warning: Current version has unescaped character issue ([#3](https://github.com/curbengh/hexo-nofollow/issues/3), [#4](https://github.com/curbengh/hexo-nofollow/issues/4)) caused by a [bug in cheerio](https://github.com/cheeriojs/cheerio/issues/1198). Read [below section](#unescaped-character-issue) for a temporary fix.
  10
  11 Adds nofollow attribute to all external links in your hexo blog posts automatically.
  12
  13 This is an updated version of [hexo-autonofollow](https://www.npmjs.com/package/hexo-autonofollow). All the options are the same, so you can use this as a drop-in replacement.
  14
  15 ## Features
  16 * Add `rel="external nofollow noopener noreferrer"` to all external links for security, privacy and SEO. [Read more](https://developer.mozilla.org/en-US/docs/Web/HTML/Link_types).
  17 * Add `target="_blank"`, Open external links in new window or tab. This can be disabled, see below.
  18
  19 Hexo doesn't insert `target="_blank"` to all external links even if you set `external_link: true` (default value) in the _config.yml.
  20 This plugin make sure all external links are processed.
  21
  22 For example,
  23 ```markdown
  24 [example-link](https://example.com)
  25 ```
  26 Becomes,
  27 ```html
  28 <a href="https://example.com" rel="external nofollow noopener noreferrer" target="_blank">example-link</a>
  29 ```
  30
  31 ## Install
  32 ``` bash
  33 $ npm install hexo-nofollow --save
  34 ```
  35
  36 ## Usage
  37 To enable this plugin, insert the following to `_config.yml`:
  38 ``` yaml
  39 nofollow:
  40   enable: true
  41 ```
  42 To exclude certain links, see below.
  43
  44 ## Options
  45 ```yaml
  46 nofollow:
  47   enable: true
  48   exclude:
  49     - 'exclude1.com'
  50     - 'exclude2.com'
  51 external_link: true
  52 ```
  53
  54 - **enable** - Enable the plugin. Defaults to `false`.
  55 - **exclude** - Exclude hostname. Specify subdomain when applicable, including `www`
  56   - `'exclude1.com'` does not apply to `www.exclude1.com` nor `en.exclude1.com`.
  57 - **external_link** - Add `target="_blank"`. [Defaults](https://hexo.io/docs/configuration#Writing) to `true`. [Recommend](https://css-tricks.com/use-target_blank/) to set it to false.
  58
  59 ***Note:*** **external_link** setting is already in the default `_config.yml`.
  60
  61 ## Unescaped character issue
  62
  63 Embedding HTML/XML in a codeblock in your post could cause issue when using this plugin with a minifier (see issue [#3](https://github.com/curbengh/hexo-nofollow/issues/3), [#4](https://github.com/curbengh/hexo-nofollow/issues/4)). This issue is caused by cheerio, the sole dependency of this plugin. In newer version (v1.0+) of cheerio, it does not properly escape character such as angle bracket, causing invalid syntax (e.g. `<<span>`) in the resulting html. While web browsers might render it just fine, minifier such as [html-minifier](https://github.com/kangax/html-minifier) requires strict syntax.
  64
  65 This issue has been [reported upstream](https://github.com/cheeriojs/cheerio/issues/1198) and [a fix](https://github.com/cheeriojs/dom-serializer/pull/80) has been proposed.
  66
  67 Meanwhile, I have included the fix in [v2.0](https://github.com/curbengh/hexo-nofollow/tree/v2.0) branch. To install this fix, change the version number of hexo-nofollow in your package.json to:
  68
  69 ``` diff
  70 - "hexo-nofollow": "^1.0.10"
  71 + "hexo-nofollow": "curbengh/hexo-nofollow#v2.0"
  72 ```
  73
  74 and run `npm install --only=prod`.
  75
  76 ## Credits
  77 All credits go to the following work:
  78 - [hexo-autonofollow](https://github.com/curbengh/hexo-nofollow) by liuzc
  79 - [cheerio](https://github.com/cheeriojs/cheerio)
  80 - `target="_blank"` behaviour is noticed through this [commit](https://github.com/SukkaW/hexo-filter-nofollow/commit/6c5f49fb551237b42413c158b9294d58c4c8b221)