Improve link handling in API docs

config/jsdoc/api/conf.json

@@ -14,7 +14,7 @@
     ]
   },
   "plugins": [
-    "plugins/markdown",
+    "config/jsdoc/api/plugins/markdown",
     "config/jsdoc/api/plugins/convert-types",
     "config/jsdoc/api/plugins/normalize-longnames",
     "config/jsdoc/api/plugins/inline-options",

config/jsdoc/api/plugins/markdown.js

@@ -0,0 +1,111 @@
+/**
+ * Modified from JSDoc's plugins/markdown and lib/jsdoc/util/markdown modules
+ * (see https://github.com/jsdoc3/jsdoc/), which are licensed under the Apache 2
+ * license (see http://www.apache.org/licenses/LICENSE-2.0).
+ *
+ * This version does not protect http(s) urls from being turned into links, and
+ * works around an issue with `~` characters in module paths by escaping them.
+ */
+
+const marked = require('marked');
+const format = require('util').format;
+
+const tags = [
+  'author',
+  'classdesc',
+  'description',
+  'exceptions',
+  'params',
+  'properties',
+  'returns',
+  'see',
+  'summary'
+];
+
+const hasOwnProp = Object.prototype.hasOwnProperty;
+
+const markedRenderer = new marked.Renderer();
+
+// Allow prettyprint to work on inline code samples
+markedRenderer.code = function(code, language) {
+  const langClass = language ? ' lang-' + language : '';
+
+  return format('<pre class="prettyprint source%s"><code>%s</code></pre>',
+    langClass, escapeCode(code));
+};
+
+function escapeCode(source) {
+  return source.replace(/</g, '&lt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+function escapeUnderscoresAndTildes(source) {
+  return source.replace(/\{@[^}\r\n]+\}/g, function(wholeMatch) {
+    return wholeMatch
+      .replace(/(^|[^\\])_/g, '$1\\_')
+      .replace('~', '&tilde;');
+  });
+}
+
+function unencodeQuotesAndTildes(source) {
+  return source.replace(/\{@[^}\r\n]+\}/g, function(wholeMatch) {
+    return wholeMatch
+      .replace(/&quot;/g, '"')
+      .replace(/&tilde;/g, '~');
+  });
+}
+
+function parse(source) {
+  let result;
+
+  source = escapeUnderscoresAndTildes(source);
+
+  result = marked(source, {renderer: markedRenderer})
+    .replace(/\s+$/, '')
+    .replace(/&#39;/g, '\'');
+
+  result = unencodeQuotesAndTildes(result);
+
+  return result;
+}
+
+function shouldProcessString(tagName, text) {
+  let shouldProcess = true;
+
+  // we only want to process `@author` and `@see` tags that contain Markdown links
+  if ((tagName === 'author' || tagName === 'see') && text.indexOf('[') === -1) {
+    shouldProcess = false;
+  }
+
+  return shouldProcess;
+}
+
+function process(doclet) {
+  tags.forEach(function(tag) {
+    if (!hasOwnProp.call(doclet, tag)) {
+      return;
+    }
+
+    if (typeof doclet[tag] === 'string' && shouldProcessString(tag, doclet[tag])) {
+      doclet[tag] = parse(doclet[tag]);
+    } else if (Array.isArray(doclet[tag])) {
+      doclet[tag].forEach(function(value, index, original) {
+        const inner = {};
+
+        inner[tag] = value;
+        process(inner);
+        original[index] = inner[tag];
+      });
+    } else if (doclet[tag]) {
+      process(doclet[tag]);
+    }
+  });
+}
+
+
+exports.handlers = {
+  newDoclet: function(e) {
+    process(e.doclet);
+  }
+};

config/jsdoc/api/template/static/scripts/main.js

@@ -113,9 +113,4 @@ $(function () {
 
     $(window).on('hashchange', _onHashChange);
     _onHashChange();
-
-    // Make links that JSDoc forgot clickable
-    $('p').each(function(i, p) {
-      p.innerHTML = anchorme(p.innerHTML);
-    });
 });

config/jsdoc/api/template/tmpl/layout.tmpl

@@ -14,7 +14,6 @@ var version = obj.packageInfo.version;
     <meta charset="utf-8">
     <title>OpenLayers v<?js= version ?> API - <?js= title ?></title>
     <script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=fetch"></script>
-    <script src="https://cdn.jsdelivr.net/gh/alexcorvi/anchorme.js@f9933f299279974caf7df4733d8fb58f8acd492e/dist-browser/anchorme.min.js"></script>
     <script src="scripts/prettify/prettify.js"> </script>
     <script src="scripts/prettify/lang-css.js"> </script>
     <script src="scripts/jquery.min.js"> </script>