Refactor docs

Author: wooorm

lib/index.js

@@ -72,7 +72,39 @@
  *   Configuration.
  *
  * @typedef UrlConfig
- *   Hosted Git info
+ *   Hosted Git info.
+ *
+ *   ###### Notes
+ *
+ *   For this repository (`remarkjs/remark-validate-links` on GitHub)
+ *   `urlConfig` looks as follows:
+ *
+ *   ```js
+ *   {
+ *     // Domain of URLs:
+ *     hostname: 'github.com',
+ *     // Path prefix before files:
+ *     prefix: '/remarkjs/remark-validate-links/blob/',
+ *     // Prefix of headings:
+ *     headingPrefix: '#',
+ *     // Hash to top of markdown documents:
+ *     topAnchor: '#readme',
+ *     // Whether lines in files can be linked:
+ *     lines: true
+ *   }
+ *   ```
+ *
+ *   If this project were hosted on Bitbucket, it would be:
+ *
+ *   ```js
+ *   {
+ *     hostname: 'bitbucket.org',
+ *     prefix: '/remarkjs/remark-validate-links/src/',
+ *     headingPrefix: '#markdown-header-',
+ *     lines: false
+ *   }
+ *   ```
+ *
  * @property {string | null | undefined} [headingPrefix]
  *   Prefix of headings (example: `'#'`, `'#markdown-header-'`).
  * @property {string | null | undefined} [hostname]
@@ -132,8 +164,13 @@ const readmeExtensions = new Set(['.markdown', '.mdown', '.mkdn', '.md'])
 const readmeBasename = /^readme$/i
 
 /**
- * Validate that Markdown links and images reference existing local files and
- * headings.
+ * Check that markdown links and images point to existing local files and
+ * headings in a Git repo.
+ *
+ * > ⚠️ **Important**: The API in Node.js checks links to headings and files
+ * > but does not check whether headings in other files exist.
+ * > The API in browsers only checks links to headings in the same file.
+ * > The CLI can check everything.
  *
  * @param {Readonly<Options> | null | undefined} [options]
  *   Configuration (optional).