Merge pull request microsoft#1841 from rbuckton/fix1840

octogonz · web-flow · commit c21423bb15aa · 2020-04-23T21:22:55.000-07:00
Fix link emit for xref containing #
diff --git a/apps/api-documenter/src/documenters/YamlDocumenter.ts b/apps/api-documenter/src/documenters/YamlDocumenter.ts
@@ -666,7 +666,16 @@ export class YamlDocumenter {
       onGetFilenameForApiItem: (apiItem: ApiItem) => {
         // NOTE: GitHub's markdown renderer does not resolve relative hyperlinks correctly
         // unless they start with "./" or "../".
-        return `xref:${this._getUid(apiItem)}`;
+
+        // To ensure the xref is properly escaped, we first encode the entire xref
+        // to handle escaping of reserved characters. Then we must replace '#' and '?'
+        // characters so that they are not interpreted as a querystring or hash.
+        // We must also backslash-escape unbalanced `(` and `)` characters as the
+        // markdown spec insists that they are only valid when balanced. To reduce
+        // the overhead we only support balanced parenthesis with a depth of 1.
+        return encodeURI(`xref:${this._getUid(apiItem)}`)
+          .replace(/[#?]/g, s => encodeURIComponent(s))
+          .replace(/(\([^(]*\))|[()]/g, (s, balanced) => balanced || ('\\' + s));
       }
     });
 
diff --git a/build-tests/api-documenter-test/etc/yaml/api-documenter-test/docclass1.yml b/build-tests/api-documenter-test/etc/yaml/api-documenter-test/docclass1.yml
@@ -3,10 +3,10 @@ items:
   - uid: 'api-documenter-test!DocClass1:class'
     summary: This is an example class.
     remarks: >-
-      [Link to overload 1](xref:api-documenter-test!DocClass1#exampleFunction:member(1))
+      [Link to overload 1](xref:api-documenter-test!DocClass1%23exampleFunction:member(1))
 
 
-      [Link to overload 2](xref:api-documenter-test!DocClass1#exampleFunction:member(2))
+      [Link to overload 2](xref:api-documenter-test!DocClass1%23exampleFunction:member(2))
 
 
 
diff --git a/common/changes/@microsoft/api-documenter/fix1840_2020-04-23-03-15.json b/common/changes/@microsoft/api-documenter/fix1840_2020-04-23-03-15.json
@@ -0,0 +1,11 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/api-documenter",
+      "comment": "Properly encode xrefs that contain '#' characters.",
+      "type": "patch"
+    }
+  ],
+  "packageName": "@microsoft/api-documenter",
+  "email": "ron.buckton@microsoft.com"
+}
