README.md in jekyll-external-links-1.0.0 vs README.md in jekyll-external-links-1.0.1

@@ -1,17 +1,26 @@
 # Jekyll plugin that marks external links
 
-In each Jekyll document or page content, updates `<a>` elements that point
-to external sites as follows:
+In rendered HTML contents of each Jekyll document or page,
+updates `<a>` elements that point to external sites as follows:
 
 - Adds `rel="external"` attribute
 - Adds inner HTML markup with external link icon
 
-You can specify a CSS selector for which links are to be marked,
+You can specify a CSS selector for which links are to be evaluated,
 and a list of selectors for which links are to be ignored
 (ignored selectors take precedence).
 
+## Which links are considered external
+
+A link is considered external if:
+
+* Its `href` attribute value starts with “http” or “https”, and
+* The domain name following “http(s)://” is not equal to the
+  domain name part from your site URL
+  (which you have to specify as `url` in Jekyll configuration).
+
 ## Configuration
 
 Example configuration with defaults:
 
 ```
@@ -22,14 +31,45 @@
     - a[href*=coverity]
     - a[href*=codecov]
   marker_html: "<span class='ico-ext'><i class='fas fa-external-link-square-alt'></i></span>"
 ```
 
-As you can see, by default the Font Awesome’s `fa-external-link-square-alt` icon is used,
-which implies that you are using Font Awesome.
+Note the assumptions made by the defaults:
 
-You can set marker_html to empty string and style links with custom CSS rule
+* Links you want to be marked as external are always within the `<main>` tag.
+
+* You use Font Awesome in your site.
+
+* Links containing “travis”, “coverity” and “codecov”
+  are only used in badges, and you don’t want to process those.
+
+If some of these assumptions don’t apply to your site,
+you can add that structure to your `_config.yml` and customize the values.
+
+### `external_links.selector`
+
+Only links matching this CSS path will be processed.
+
+### `external_links.marker_html`
+
+The specified HTML markup will be added inside each `<a>` tag
+that’s detected as external link.
+
+By default, the Font Awesome’s `fa-external-link-square-alt` icon is used,
+which requires your site to have Font Awesome initialized.
+
+You can set `marker_html` to empty string and style links with a custom CSS rule
 (e.g., `a[rel=external] { border-bottom-style: dashed; }`), though it’s less flexible.
+
+### `external_links.ignored_selectors`
+
+Even if a link matches `selector`, it won’t be altered if it also matches any of these
+selectors.
+
+### `url`
+
+The `url` option in your configuration file is used when deciding
+whether a given link is external or not.
 
 ## Example site
 
 An example site is included in this repo.
 Use it to demo the plugin and to test it during development.