Changed reference resolving to happen post-render.

Also updated api schemas to reflect the change from $ref:api.node to $(ref:api.node)

NOTRY=true

Review URL: https://codereview.chromium.org/132953002

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@248805 0039d316-1c4b-4281-b951-d872f2087c98

23 files changed, 226 insertions, 109 deletions

diff --git a/chrome/common/extensions/api/content_settings.json b/chrome/common/extensions/api/content_settings.json
index 2a0b86a..9fcfb28 100644
--- a/chrome/common/extensions/api/content_settings.json
+++ b/chrome/common/extensions/api/content_settings.json
@@ -24,7 +24,7 @@
             "description": "A human readable description of the resource."
           }
         },
-        "description": "The only content type using resource identifiers is $ref:contentSettings.plugins. For more information, see <a href=\"contentSettings.html#resource-identifiers\">Resource Identifiers</a>."
+        "description": "The only content type using resource identifiers is $(ref:contentSettings.plugins). For more information, see <a href=\"contentSettings.html#resource-identifiers\">Resource Identifiers</a>."
       },
       {
         "id": "ContentSetting",
diff --git a/chrome/common/extensions/api/declarative_content.json b/chrome/common/extensions/api/declarative_content.json
index 7d227ec..cc74bec 100644
--- a/chrome/common/extensions/api/declarative_content.json
+++ b/chrome/common/extensions/api/declarative_content.json
@@ -40,7 +40,7 @@
       },
       {
         "id": "ShowPageAction",
-        "description": "Declarative event action that shows the extension's $ref:[pageAction page action] while the corresponding conditions are met.  This action can be used without <a href=\"declare_permissions.html#host-permissions\">host permissions</a>, but the extension must have a page action.  If the extension takes the <a href=\"activeTab.html\">activeTab</a> permission, a click on the page action will grant access to the active tab.",
+        "description": "Declarative event action that shows the extension's $(ref:pageAction page action) while the corresponding conditions are met.  This action can be used without <a href=\"declare_permissions.html#host-permissions\">host permissions</a>, but the extension must have a page action.  If the extension takes the <a href=\"activeTab.html\">activeTab</a> permission, a click on the page action will grant access to the active tab.",
         "type": "object",
         "properties": {
           "instanceType": {
diff --git a/chrome/common/extensions/api/declarative_web_request.json b/chrome/common/extensions/api/declarative_web_request.json
index 2c37c74..77bdb1e36 100644
--- a/chrome/common/extensions/api/declarative_web_request.json
+++ b/chrome/common/extensions/api/declarative_web_request.json
@@ -297,7 +297,7 @@
       },
       {
         "id": "declarativeWebRequest.SendMessageToExtension",
-        "description": "Triggers the $ref:declarativeWebRequest.onMessage event.",
+        "description": "Triggers the $(ref:declarativeWebRequest.onMessage) event.",
         "type": "object",
         "properties": {
           "instanceType": {
@@ -570,7 +570,7 @@
       {
         "name": "onMessage",
         "type": "function",
-        "description": "Fired when a message is sent via $ref:declarativeWebRequest.SendMessageToExtension from an action of the declarative web request API.",
+        "description": "Fired when a message is sent via $(ref:declarativeWebRequest.SendMessageToExtension) from an action of the declarative web request API.",
         "parameters": [
           {
             "type": "object",
diff --git a/chrome/common/extensions/api/extension.json b/chrome/common/extensions/api/extension.json
index e12c87e..efb7f4b 100644
--- a/chrome/common/extensions/api/extension.json
+++ b/chrome/common/extensions/api/extension.json
@@ -28,10 +28,10 @@
       {
         "name": "sendRequest",
         "nocompile": true,
-        "deprecated": "Please use $ref:runtime.sendMessage.",
+        "deprecated": "Please use $(ref:runtime.sendMessage).",
         "type": "function",
         "allowAmbiguousOptionalArguments": true,
-        "description": "Sends a single request to other listeners within the extension. Similar to $ref:runtime.connect, but only sends a single request with an optional response. The $ref:onRequest event is fired in each page of the extension.",
+        "description": "Sends a single request to other listeners within the extension. Similar to $(ref:runtime.connect), but only sends a single request with an optional response. The $(ref:extension.onRequest) event is fired in each page of the extension.",
         "parameters": [
           {"type": "string", "name": "extensionId", "optional": true, "description": "The extension ID of the extension you want to connect to. If omitted, default is your own extension."},
           { "type": "any", "name": "request" },
@@ -43,7 +43,7 @@
               {
                 "name": "response",
                 "type": "any",
-                "description": "The JSON response object sent by the handler of the request. If an error occurs while connecting to the extension, the callback will be called with no arguments and $ref:runtime.lastError will be set to the error message."
+                "description": "The JSON response object sent by the handler of the request. If an error occurs while connecting to the extension, the callback will be called with no arguments and $(ref:runtime.lastError) will be set to the error message."
               }
             ]
           }
@@ -119,7 +119,7 @@
       {
         "name": "getExtensionTabs",
         "nocompile": true,
-        "deprecated": "Please use $ref:getViews <code>{type: \"tab\"}</code>.",
+        "deprecated": "Please use $(ref:extension.getViews) <code>{type: \"tab\"}</code>.",
         "type": "function",
         "maximumManifestVersion": 1,
         "description": "Returns an array of the JavaScript 'window' objects for each of the tabs running inside the current extension. If <code>windowId</code> is specified, returns only the 'window' objects of tabs attached to the specified window.",
@@ -187,7 +187,7 @@
     "events": [
       {
         "name": "onRequest",
-        "deprecated": "Please use $ref:runtime.onMessage.",
+        "deprecated": "Please use $(ref:runtime.onMessage).",
         "type": "function",
         "options": {
           "unmanaged": true
@@ -201,7 +201,7 @@
       },
       {
         "name": "onRequestExternal",
-        "deprecated": "Please use $ref:runtime.onMessageExternal.",
+        "deprecated": "Please use $(ref:runtime.onMessageExternal).",
         "type": "function",
         "options": {
           "unmanaged": true
@@ -215,4 +215,4 @@
       }
     ]
   }
-]
\ No newline at end of file
+]
diff --git a/chrome/common/extensions/api/gcm.json b/chrome/common/extensions/api/gcm.json
index cd81412..fbde146 100644
--- a/chrome/common/extensions/api/gcm.json
+++ b/chrome/common/extensions/api/gcm.json
@@ -32,7 +32,7 @@
           {
             "name": "callback",
             "type": "function",
-            "description": "Function called when registration completes. It should check $ref:runtime.lastError for error when <code>registrationId</code> is empty.",
+            "description": "Function called when registration completes. It should check $(ref:runtime.lastError) for error when <code>registrationId</code> is empty.",
             "parameters": [
               { 
                 "name": "registrationId",
@@ -77,14 +77,14 @@
                   "type": "string",
                   "minLength": 1
                 },
-                "description": "Message data to send to the server. <code>goog.</code> and <code>google</code> are disallowed as key prefixes. Sum of all key/value pairs should not exceed $ref:MAX_MESSAGE_SIZE."
+                "description": "Message data to send to the server. <code>goog.</code> and <code>google</code> are disallowed as key prefixes. Sum of all key/value pairs should not exceed $(ref:gcm.MAX_MESSAGE_SIZE)."
               }
             }
           },
           {
             "name": "callback",
             "type": "function",
-            "description": "A function called after the message is successfully queued for sending. $ref:runtime.lastError should be checked, to ensure a message was sent without problems.",
+            "description": "A function called after the message is successfully queued for sending. $(ref:runtime.lastError) should be checked, to ensure a message was sent without problems.",
             "parameters": [
               {
                 "name": "messageId",
diff --git a/chrome/common/extensions/api/management.json b/chrome/common/extensions/api/management.json
index f2a35d9..cf76e5b 100644
--- a/chrome/common/extensions/api/management.json
+++ b/chrome/common/extensions/api/management.json
@@ -58,7 +58,7 @@
           "isApp": {
             "description": "True if this is an app.",
             "type": "boolean",
-            "deprecated": "Please use $ref:ExtensionInfo.type."
+            "deprecated": "Please use $(ref:management.ExtensionInfo.type)."
           },
           "type": {
             "description": "The type of this extension, app, or theme.",
@@ -146,7 +146,7 @@
           {
             "name": "id",
             "type": "string",
-            "description": "The ID from an item of $ref:ExtensionInfo."
+            "description": "The ID from an item of $(ref:management.ExtensionInfo)."
           },
           {
             "type": "function",
@@ -213,7 +213,7 @@
           {
             "name": "id",
             "type": "string",
-            "description": "This should be the id from an item of $ref:ExtensionInfo."
+            "description": "This should be the id from an item of $(ref:management.ExtensionInfo)."
           },
           {
             "name": "enabled",
@@ -235,7 +235,7 @@
           {
             "name": "id",
             "type": "string",
-            "description": "This should be the id from an item of $ref:ExtensionInfo."
+            "description": "This should be the id from an item of $(ref:management.ExtensionInfo)."
           },
           {
             "type": "object",
diff --git a/chrome/common/extensions/api/manifest_types.json b/chrome/common/extensions/api/manifest_types.json
index 7f8f3af..ef006dd 100644
--- a/chrome/common/extensions/api/manifest_types.json
+++ b/chrome/common/extensions/api/manifest_types.json
@@ -32,7 +32,7 @@
             "items": {"type": "string"}
           },
           "accepts_tls_channel_id": {
-            "description": "If <code>true</code>, messages sent via $ref:runtime.connect or $ref:runtime.sendMessage will set $ref:runtime.MessageSender.tlsChannelId if those methods request it to be. If <code>false</code>, $ref:runtime.MessageSender.tlsChannelId will never be set under any circumstance.",
+            "description": "If <code>true</code>, messages sent via $(ref:runtime.connect) or $(ref:runtime.sendMessage) will set $(ref:runtime.MessageSender.tlsChannelId) if those methods request it to be. If <code>false</code>, $(ref:runtime.MessageSender.tlsChannelId) will never be set under any circumstance.",
             "optional": true,
             "type": "boolean"
           }
diff --git a/chrome/common/extensions/api/permissions.json b/chrome/common/extensions/api/permissions.json
index 63bf434..e5a408f 100644
--- a/chrome/common/extensions/api/permissions.json
+++ b/chrome/common/extensions/api/permissions.json
@@ -96,7 +96,7 @@
       {
         "name": "request",
         "type": "function",
-        "description": "Requests access to the specified permissions. These permissions must be defined in the optional_permissions field of the manifest. If there are any problems requesting the permissions, $ref:runtime.lastError will be set.",
+        "description": "Requests access to the specified permissions. These permissions must be defined in the optional_permissions field of the manifest. If there are any problems requesting the permissions, $(ref:runtime.lastError) will be set.",
         "parameters": [
           {
             "name": "permissions",
@@ -119,7 +119,7 @@
       {
         "name": "remove",
         "type": "function",
-        "description": "Removes access to the specified permissions. If there are any problems removing the permissions, $ref:runtime.lastError will be set.",
+        "description": "Removes access to the specified permissions. If there are any problems removing the permissions, $(ref:runtime.lastError) will be set.",
         "parameters": [
           {
             "name": "permissions",
diff --git a/chrome/common/extensions/api/runtime.json b/chrome/common/extensions/api/runtime.json
index 8a212b8..83a18b6 100644
--- a/chrome/common/extensions/api/runtime.json
+++ b/chrome/common/extensions/api/runtime.json
@@ -31,7 +31,7 @@
         "type": "object",
         "description": "An object containing information about the script context that sent a message or request.",
         "properties": {
-          "tab": {"$ref": "tabs.Tab", "optional": true, "description": "The $ref:tabs.Tab which opened the connection, if any. This property will <strong>only</strong> be present when the connection was opened from a tab (including content scripts), and <strong>only</strong> if the receiver is an extension, not an app."},
+          "tab": {"$ref": "tabs.Tab", "optional": true, "description": "The $(ref:tabs.Tab) which opened the connection, if any. This property will <strong>only</strong> be present when the connection was opened from a tab (including content scripts), and <strong>only</strong> if the receiver is an extension, not an app."},
           "id": {"type": "string", "optional": true, "description": "The ID of the extension or app that opened the connection, if any."},
           "url": {"type": "string", "optional": true, "description": "The URL of the page or frame that opened the connection, if any. This property will <strong>only</strong> be present when the connection was opened from a tab or content script."},
           "tlsChannelId": {"type": "string", "optional": true, "description": "The TLS channel ID of the web page that opened the connection, if requested by the extension or app, and if available."}
@@ -172,7 +172,7 @@
         "name": "connect",
         "type": "function",
         "nocompile": true,
-        "description": "Attempts to connect to connect listeners within an extension/app (such as the background page), or other extensions/apps. This is useful for content scripts connecting to their extension processes, inter-app/extension communication, and <a href=\"manifest/externally_connectable.html\">web messaging</a>. Note that this does not connect to any listeners in a content script. Extensions may connect to content scripts embedded in tabs via $ref:tabs.connect.",
+        "description": "Attempts to connect to connect listeners within an extension/app (such as the background page), or other extensions/apps. This is useful for content scripts connecting to their extension processes, inter-app/extension communication, and <a href=\"manifest/externally_connectable.html\">web messaging</a>. Note that this does not connect to any listeners in a content script. Extensions may connect to content scripts embedded in tabs via $(ref:tabs.connect).",
         "parameters": [
           {"type": "string", "name": "extensionId", "optional": true, "description": "The ID of the extension or app to connect to. If omitted, a connection will be attempted with your own extension. Required if sending messages from a web page for <a href=\"manifest/externally_connectable.html\">web messaging</a>."},
           {
@@ -187,7 +187,7 @@
         ],
         "returns": {
           "$ref": "Port",
-          "description": "Port through which messages can be sent and received. The port's $ref:[runtime.Port onDisconnect] event is fired if the extension/app does not exist. "
+          "description": "Port through which messages can be sent and received. The port's $(ref:runtime.Port onDisconnect) event is fired if the extension/app does not exist. "
         }
       },
       {
@@ -212,7 +212,7 @@
         "type": "function",
         "nocompile": true,
         "allowAmbiguousOptionalArguments": true,
-        "description": "Sends a single message to event listeners within your extension/app or a different extension/app. Similar to $ref:runtime.connect but only sends a single message, with an optional response. If sending to your extension, the $ref:runtime.onMessage event will be fired in each page, or $ref:runtime.onMessageExternal, if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use $ref:tabs.sendMessage.",
+        "description": "Sends a single message to event listeners within your extension/app or a different extension/app. Similar to $(ref:runtime.connect) but only sends a single message, with an optional response. If sending to your extension, the $(ref:runtime.onMessage) event will be fired in each page, or $(ref:runtime.onMessageExternal), if a different extension. Note that extensions cannot send messages to content scripts using this method. To send messages to content scripts, use $(ref:tabs.sendMessage).",
         "parameters": [
           {"type": "string", "name": "extensionId", "optional": true, "description": "The ID of the extension/app to send the message to. If omitted, the message will be sent to your own extension/app. Required if sending messages from a web page for <a href=\"manifest/externally_connectable.html\">web messaging</a>."},
           { "type": "any", "name": "message" },
@@ -232,7 +232,7 @@
               {
                 "name": "response",
                 "type": "any",
-                "description": "The JSON response object sent by the handler of the message. If an error occurs while connecting to the extension, the callback will be called with no arguments and $ref:runtime.lastError will be set to the error message."
+                "description": "The JSON response object sent by the handler of the message. If an error occurs while connecting to the extension, the callback will be called with no arguments and $(ref:runtime.lastError) will be set to the error message."
               }
             ]
           }
@@ -265,7 +265,7 @@
               {
                 "name": "response",
                 "type": "any",
-                "description": "The response message sent by the native messaging host. If an error occurs while connecting to the native messaging host, the callback will be called with no arguments and $ref:runtime.lastError will be set to the error message.",
+                "description": "The response message sent by the native messaging host. If an error occurs while connecting to the native messaging host, the callback will be called with no arguments and $(ref:runtime.lastError) will be set to the error message.",
                 "additionalProperties": {
                   "type": "any"
                 }
@@ -393,7 +393,7 @@
         "name": "onBrowserUpdateAvailable",
         "type": "function",
         "description": "Fired when a Chrome update is available, but isn't installed immediately because a browser restart is required.",
-        "deprecated": "Please use $ref:onRestartRequired.",
+        "deprecated": "Please use $(ref:runtime.onRestartRequired).",
         "parameters": []
       },
       {
diff --git a/chrome/common/extensions/api/sessions.json b/chrome/common/extensions/api/sessions.json
index 48c09e9..a063d92 100644
--- a/chrome/common/extensions/api/sessions.json
+++ b/chrome/common/extensions/api/sessions.json
@@ -16,7 +16,7 @@
             "minimum": 0,
             "maximum": 25,
             "optional": true,
-            "description": "The maximum number of entries to be fetched in the requested list. Omit this parameter to fetch the maximum number of entries ($ref:MAX_SESSION_RESULTS)."
+            "description": "The maximum number of entries to be fetched in the requested list. Omit this parameter to fetch the maximum number of entries ($(ref:sessions.MAX_SESSION_RESULTS))."
           }
         }
       },
@@ -25,8 +25,8 @@
         "type": "object",
         "properties": {
           "lastModified": {"type": "integer", "description": "The time when the window or tab was closed or modified, represented in milliseconds since the epoch."},
-          "tab": {"$ref": "tabs.Tab", "optional": true, "description": "The $ref:tabs.Tab, if this entry describes a tab. Either this or $ref:Session.window will be set."},
-          "window": {"$ref": "windows.Window", "optional": true, "description": "The $ref:windows.Window, if this entry describes a window. Either this or $ref:Session.tab will be set."}
+          "tab": {"$ref": "tabs.Tab", "optional": true, "description": "The $(ref:tabs.Tab), if this entry describes a tab. Either this or $(ref:sessions.Session.window) will be set."},
+          "window": {"$ref": "windows.Window", "optional": true, "description": "The $(ref:windows.Window), if this entry describes a window. Either this or $(ref:sessions.Session.tab) will be set."}
         }
       },
       {
@@ -75,7 +75,7 @@
             "name": "callback",
             "parameters": [
               {
-                "name": "devices", "type": "array", "items": { "$ref": "Device" }, "description": "The list of $ref:Device objects for each synced session, sorted in order from device with most recently modified session to device with least recently modified session. $ref:tabs.Tab objects are sorted by recency in the $ref:windows.Window of the $ref:Session objects."
+                "name": "devices", "type": "array", "items": { "$ref": "Device" }, "description": "The list of $(ref:sessions.Device) objects for each synced session, sorted in order from device with most recently modified session to device with least recently modified session. $(ref:tabs.Tab) objects are sorted by recency in the $(ref:windows.Window) of the $(ref:sessions.Session) objects."
               }
             ]
           }
@@ -84,13 +84,13 @@
       {
         "name": "restore",
         "type": "function",
-        "description": "Reopens a $ref:windows.Window or $ref:tabs.Tab, with an optional callback to run when the entry has been restored.",
+        "description": "Reopens a $(ref:windows.Window) or $(ref:tabs.Tab), with an optional callback to run when the entry has been restored.",
         "parameters": [
           {
             "type": "string",
             "name": "sessionId",
             "optional": true,
-            "description": "The $ref:windows.Window.sessionId, or $ref:tabs.Tab.sessionId to restore."
+            "description": "The $(ref:windows.Window.sessionId), or $(ref:tabs.Tab.sessionId) to restore."
           },
           {
             "type": "function",
@@ -100,7 +100,7 @@
               {
                 "$ref": "Session",
                 "name": "restoredSession",
-                "description": "A $ref:Session containing the restored $ref:windows.Window or $ref:tabs.Tab object."
+                "description": "A $(ref:sessions.Session) containing the restored $(ref:windows.Window) or $(ref:tabs.Tab) object."
               }
             ]
           }
@@ -110,7 +110,7 @@
     "properties": {
       "MAX_SESSION_RESULTS": {
         "value": 25,
-        "description": "The maximum number of $ref:Session that will be included in a requested list."
+        "description": "The maximum number of $(ref:sessions.Session) that will be included in a requested list."
       }
     }
   }
diff --git a/chrome/common/extensions/api/storage.json b/chrome/common/extensions/api/storage.json
index 8f32f68..ee98964 100644
--- a/chrome/common/extensions/api/storage.json
+++ b/chrome/common/extensions/api/storage.json
@@ -51,7 +51,7 @@
               {
                 "name": "callback",
                 "type": "function",
-                "description": "Callback with storage items, or on failure (in which case $ref:runtime.lastError will be set).",
+                "description": "Callback with storage items, or on failure (in which case $(ref:runtime.lastError) will be set).",
                 "parameters": [
                   {
                     "name": "items",
@@ -80,7 +80,7 @@
               {
                 "name": "callback",
                 "type": "function",
-                "description": "Callback with the amount of space being used by storage, or on failure (in which case $ref:runtime.lastError will be set).",
+                "description": "Callback with the amount of space being used by storage, or on failure (in which case $(ref:runtime.lastError) will be set).",
                 "parameters": [
                   {
                     "name": "bytesInUse",
@@ -105,7 +105,7 @@
               {
                 "name": "callback",
                 "type": "function",
-                "description": "Callback on success, or on failure (in which case $ref:runtime.lastError will be set).",
+                "description": "Callback on success, or on failure (in which case $(ref:runtime.lastError) will be set).",
                 "parameters": [],
                 "optional": true
               }
@@ -127,7 +127,7 @@
               {
                 "name": "callback",
                 "type": "function",
-                "description": "Callback on success, or on failure (in which case $ref:runtime.lastError will be set).",
+                "description": "Callback on success, or on failure (in which case $(ref:runtime.lastError) will be set).",
                 "parameters": [],
                 "optional": true
               }
@@ -141,7 +141,7 @@
               {
                 "name": "callback",
                 "type": "function",
-                "description": "Callback on success, or on failure (in which case $ref:runtime.lastError will be set).",
+                "description": "Callback on success, or on failure (in which case $(ref:runtime.lastError) will be set).",
                 "parameters": [],
                 "optional": true
               }
@@ -160,7 +160,7 @@
             "name": "changes",
             "type": "object",
             "additionalProperties": { "$ref": "StorageChange" },
-            "description": "Object mapping each key that changed to its corresponding $ref:StorageChange for that item."
+            "description": "Object mapping each key that changed to its corresponding $(ref:storage.StorageChange) for that item."
           },
           {
             "name": "areaName",
@@ -178,23 +178,23 @@
         "properties": {
           "QUOTA_BYTES": {
             "value": 102400,
-            "description": "The maximum total amount (in bytes) of data that can be stored in sync storage, as measured by the JSON stringification of every value plus every key's length. Updates that would cause this limit to be exceeded fail immediately and set $ref:runtime.lastError."
+            "description": "The maximum total amount (in bytes) of data that can be stored in sync storage, as measured by the JSON stringification of every value plus every key's length. Updates that would cause this limit to be exceeded fail immediately and set $(ref:runtime.lastError)."
           },
           "QUOTA_BYTES_PER_ITEM": {
             "value": 4096,
-            "description": "The maximum size (in bytes) of each individual item in sync storage, as measured by the JSON stringification of its value plus its key length. Updates containing items larger than this limit will fail immediately and set $ref:runtime.lastError."
+            "description": "The maximum size (in bytes) of each individual item in sync storage, as measured by the JSON stringification of its value plus its key length. Updates containing items larger than this limit will fail immediately and set $(ref:runtime.lastError)."
           },
           "MAX_ITEMS": {
             "value": 512,
-            "description": "The maximum number of items that can be stored in sync storage. Updates that would cause this limit to be exceeded will fail immediately and set $ref:runtime.lastError."
+            "description": "The maximum number of items that can be stored in sync storage. Updates that would cause this limit to be exceeded will fail immediately and set $(ref:runtime.lastError)."
           },
           "MAX_WRITE_OPERATIONS_PER_HOUR": {
             "value": 1000,
-            "description": "The maximum number of <code>set</code>, <code>remove</code>, or <code>clear</code> operations that can be performed each hour. Updates that would cause this limit to be exceeded fail immediately and set $ref:runtime.lastError."
+            "description": "The maximum number of <code>set</code>, <code>remove</code>, or <code>clear</code> operations that can be performed each hour. Updates that would cause this limit to be exceeded fail immediately and set $(ref:runtime.lastError)."
           },
           "MAX_SUSTAINED_WRITE_OPERATIONS_PER_MINUTE": {
             "value": 10,
-            "description": "The maximum number of <code>set</code>, <code>remove</code>, or <code>clear</code> operations that can be performed each minute, sustained over 10 minutes. Updates that would cause this limit to be exceeded fail immediately and set $ref:runtime.lastError."
+            "description": "The maximum number of <code>set</code>, <code>remove</code>, or <code>clear</code> operations that can be performed each minute, sustained over 10 minutes. Updates that would cause this limit to be exceeded fail immediately and set $(ref:runtime.lastError)."
           }
         }
       },
@@ -205,7 +205,7 @@
         "properties": {
           "QUOTA_BYTES": {
             "value": 5242880,
-            "description": "The maximum amount (in bytes) of data that can be stored in local storage, as measured by the JSON stringification of every value plus every key's length. This value will be ignored if the extension has the <code>unlimitedStorage</code> permission. Updates that would cause this limit to be exceeded fail immediately and set $ref:runtime.lastError."
+            "description": "The maximum amount (in bytes) of data that can be stored in local storage, as measured by the JSON stringification of every value plus every key's length. This value will be ignored if the extension has the <code>unlimitedStorage</code> permission. Updates that would cause this limit to be exceeded fail immediately and set $(ref:runtime.lastError)."
           }
         }
       },
diff --git a/chrome/common/extensions/api/tabs.json b/chrome/common/extensions/api/tabs.json
index ea96bc3..3bd8a57 100644
--- a/chrome/common/extensions/api/tabs.json
+++ b/chrome/common/extensions/api/tabs.json
@@ -11,12 +11,12 @@
         "id": "Tab",
         "type": "object",
         "properties": {
-          "id": {"type": "integer", "minimum": 0, "optional": true, "description": "The ID of the tab. Tab IDs are unique within a browser session. Under some circumstances a Tab may not be assigned an ID, for example when querying foreign tabs using the $ref:sessions API, in which case a session ID may be present."},
+          "id": {"type": "integer", "minimum": 0, "optional": true, "description": "The ID of the tab. Tab IDs are unique within a browser session. Under some circumstances a Tab may not be assigned an ID, for example when querying foreign tabs using the $(ref:sessions) API, in which case a session ID may be present."},
           // TODO(kalman): Investigate how this is ending up as -1 (based on window type? a bug?) and whether it should be optional instead.
           "index": {"type": "integer", "minimum": -1, "description": "The zero-based index of the tab within its window."},
           "windowId": {"type": "integer", "minimum": 0, "description": "The ID of the window the tab is contained within."},
           "openerTabId": {"type": "integer", "minimum": 0, "optional": true, "description": "The ID of the tab that opened this tab, if any. This property is only present if the opener tab still exists."},
-          "selected": {"type": "boolean", "description": "Whether the tab is selected.", "deprecated": "Please use $ref:Tab.highlighted."},
+          "selected": {"type": "boolean", "description": "Whether the tab is selected.", "deprecated": "Please use $(ref:tabs.Tab.highlighted)."},
           "highlighted": {"type": "boolean", "description": "Whether the tab is highlighted."},
           "active": {"type": "boolean", "description": "Whether the tab is active in its window. (Does not necessarily mean the window is focused.)"},
           "pinned": {"type": "boolean", "description": "Whether the tab is pinned."},
@@ -27,7 +27,7 @@
           "incognito": {"type": "boolean", "description": "Whether the tab is in an incognito window."},
           "width": {"type": "integer", "optional": true, "description": "The width of the tab in pixels."},
           "height": {"type": "integer", "optional": true, "description": "The height of the tab in pixels."},
-          "sessionId": {"type": "string", "optional": true, "description": "The session ID used to uniquely identify a Tab obtained from the $ref:sessions API."}
+          "sessionId": {"type": "string", "optional": true, "description": "The session ID used to uniquely identify a Tab obtained from the $(ref:sessions) API."}
         }
       },
       {
@@ -89,7 +89,7 @@
         "name": "connect",
         "nocompile": true,
         "type": "function",
-        "description": "Connects to the content script(s) in the specified tab. The $ref:runtime.onConnect event is fired in each content script running in the specified tab for the current extension. For more details, see <a href='messaging.html'>Content Script Messaging</a>.",
+        "description": "Connects to the content script(s) in the specified tab. The $(ref:runtime.onConnect) event is fired in each content script running in the specified tab for the current extension. For more details, see <a href='messaging.html'>Content Script Messaging</a>.",
         "parameters": [
           {
             "type": "integer",
@@ -107,15 +107,15 @@
         ],
         "returns": {
           "$ref": "runtime.Port",
-          "description": "A port that can be used to communicate with the content scripts running in the specified tab. The port's $ref:runtime.Port event is fired if the tab closes or does not exist. "
+          "description": "A port that can be used to communicate with the content scripts running in the specified tab. The port's $(ref:runtime.Port) event is fired if the tab closes or does not exist. "
         }
       },
       {
         "name": "sendRequest",
-        "deprecated": "Please use $ref:runtime.sendMessage.",
+        "deprecated": "Please use $(ref:runtime.sendMessage).",
         "nocompile": true,
         "type": "function",
-        "description": "Sends a single request to the content script(s) in the specified tab, with an optional callback to run when a response is sent back.  The $ref:extension.onRequest event is fired in each content script running in the specified tab for the current extension.",
+        "description": "Sends a single request to the content script(s) in the specified tab, with an optional callback to run when a response is sent back.  The $(ref:extension.onRequest) event is fired in each content script running in the specified tab for the current extension.",
         "parameters": [
           {
             "type": "integer",
@@ -134,7 +134,7 @@
               {
                 "name": "response",
                 "type": "any",
-                "description": "The JSON response object sent by the handler of the request. If an error occurs while connecting to the specified tab, the callback will be called with no arguments and $ref:runtime.lastError will be set to the error message."
+                "description": "The JSON response object sent by the handler of the request. If an error occurs while connecting to the specified tab, the callback will be called with no arguments and $(ref:runtime.lastError) will be set to the error message."
               }
             ]
           }
@@ -144,7 +144,7 @@
         "name": "sendMessage",
         "nocompile": true,
         "type": "function",
-        "description": "Sends a single message to the content script(s) in the specified tab, with an optional callback to run when a response is sent back.  The $ref:runtime.onMessage event is fired in each content script running in the specified tab for the current extension.",
+        "description": "Sends a single message to the content script(s) in the specified tab, with an optional callback to run when a response is sent back.  The $(ref:runtime.onMessage) event is fired in each content script running in the specified tab for the current extension.",
         "parameters": [
           {
             "type": "integer",
@@ -163,7 +163,7 @@
               {
                 "name": "response",
                 "type": "any",
-                "description": "The JSON response object sent by the handler of the message. If an error occurs while connecting to the specified tab, the callback will be called with no arguments and $ref:runtime.lastError will be set to the error message."
+                "description": "The JSON response object sent by the handler of the message. If an error occurs while connecting to the specified tab, the callback will be called with no arguments and $(ref:runtime.lastError) will be set to the error message."
               }
             ]
           }
@@ -171,7 +171,7 @@
       },
       {
         "name": "getSelected",
-        "deprecated": "Please use $ref:query <code>{active: true}</code>.",
+        "deprecated": "Please use $(ref:tabs.query) <code>{active: true}</code>.",
         "type": "function",
         "description": "Gets the tab that is selected in the specified window.",
         "parameters": [
@@ -194,7 +194,7 @@
       {
         "name": "getAllInWindow",
         "type": "function",
-        "deprecated": "Please use $ref:query <code>{windowId: windowId}</code>.",
+        "deprecated": "Please use $(ref:tabs.query) <code>{windowId: windowId}</code>.",
         "description": "Gets details about all tabs in the specified window.",
         "parameters": [
           {
@@ -242,7 +242,7 @@
               "active": {
                 "type": "boolean",
                 "optional": true,
-                "description": "Whether the tab should become the active tab in the window. Does not affect whether the window is focused (see $ref:windows.update). Defaults to <var>true</var>."
+                "description": "Whether the tab should become the active tab in the window. Does not affect whether the window is focused (see $(ref:windows.update)). Defaults to <var>true</var>."
               },
               "selected": {
                 "deprecated": "Please use <em>active</em>.",
@@ -296,7 +296,7 @@
               {
                 "name": "tab",
                 "optional": true,
-                "description": "Details about the duplicated tab. The $ref:tabs.Tab object doesn't contain <code>url</code>, <code>title</code> and <code>favIconUrl</code> if the <code>\"tabs\"</code> permission has not been requested.",
+                "description": "Details about the duplicated tab. The $(ref:tabs.Tab) object doesn't contain <code>url</code>, <code>title</code> and <code>favIconUrl</code> if the <code>\"tabs\"</code> permission has not been requested.",
                 "$ref": "Tab"
               }
             ]
@@ -357,7 +357,7 @@
                 "type": "integer",
                 "optional": true,
                 "minimum": -2,
-                "description": "The ID of the parent window, or $ref:windows.WINDOW_ID_CURRENT for the <a href='windows.html#current-window'>current window</a>."
+                "description": "The ID of the parent window, or $(ref:windows.WINDOW_ID_CURRENT) for the <a href='windows.html#current-window'>current window</a>."
               },
               "windowType": {
                 "type": "string",
@@ -449,7 +449,7 @@
               "active": {
                 "type": "boolean",
                 "optional": true,
-                "description": "Whether the tab should be active. Does not affect whether the window is focused (see $ref:windows.update)."
+                "description": "Whether the tab should be active. Does not affect whether the window is focused (see $(ref:windows.update))."
               },
               "highlighted": {
                 "type": "boolean",
@@ -484,7 +484,7 @@
                 "name": "tab",
                 "$ref": "Tab",
                 "optional": true,
-                "description": "Details about the updated tab. The $ref:tabs.Tab object doesn't contain <code>url</code>, <code>title</code> and <code>favIconUrl</code> if the <code>\"tabs\"</code> permission has not been requested."
+                "description": "Details about the updated tab. The $(ref:tabs.Tab) object doesn't contain <code>url</code>, <code>title</code> and <code>favIconUrl</code> if the <code>\"tabs\"</code> permission has not been requested."
               }
             ]
           }
@@ -728,7 +728,7 @@
       {
         "name": "onMoved",
         "type": "function",
-        "description": "Fired when a tab is moved within a window. Only one move event is fired, representing the tab the user directly moved. Move events are not fired for the other tabs that must move in response. This event is not fired when a tab is moved between windows. For that, see $ref:onDetached.",
+        "description": "Fired when a tab is moved within a window. Only one move event is fired, representing the tab the user directly moved. Move events are not fired for the other tabs that must move in response. This event is not fired when a tab is moved between windows. For that, see $(ref:tabs.onDetached).",
         "parameters": [
           {"type": "integer", "name": "tabId", "minimum": 0},
           {
@@ -744,7 +744,7 @@
       },
       {
         "name": "onSelectionChanged",
-        "deprecated": "Please use $ref:onActivated.",
+        "deprecated": "Please use $(ref:tabs.onActivated).",
         "type": "function",
         "description": "Fires when the selected tab in a window changes.",
         "parameters": [
@@ -769,9 +769,9 @@
       },
       {
         "name": "onActiveChanged",
-        "deprecated": "Please use $ref:onActivated.",
+        "deprecated": "Please use $(ref:tabs.onActivated).",
         "type": "function",
-        "description": "Fires when the selected tab in a window changes. Note that the tab's URL may not be set at the time this event fired, but you can listen to $ref:onUpdated events to be notified when a URL is set.",
+        "description": "Fires when the selected tab in a window changes. Note that the tab's URL may not be set at the time this event fired, but you can listen to $(ref:tabs.onUpdated) events to be notified when a URL is set.",
         "parameters": [
           {
             "type": "integer",
@@ -817,7 +817,7 @@
       },
       {
         "name": "onHighlightChanged",
-        "deprecated": "Please use $ref:onHighlighted.",
+        "deprecated": "Please use $(ref:tabs.onHighlighted).",
         "type": "function",
         "description": "Fired when the highlighted or selected tabs in a window changes.",
         "parameters": [
diff --git a/chrome/common/extensions/api/tts.json b/chrome/common/extensions/api/tts.json
index 995968ca..8449be6 100644
--- a/chrome/common/extensions/api/tts.json
+++ b/chrome/common/extensions/api/tts.json
@@ -231,7 +231,7 @@
                 "type": "array",
                 "name": "voices",
                 "items": { "$ref": "TtsVoice" },
-                "description": "Array of $ref:TtsVoice objects representing the available voices for speech synthesis."
+                "description": "Array of $(ref:tts.TtsVoice) objects representing the available voices for speech synthesis."
               }
             ]
           }
diff --git a/chrome/common/extensions/api/types.json b/chrome/common/extensions/api/types.json
index c5cc5fd..8244256 100644
--- a/chrome/common/extensions/api/types.json
+++ b/chrome/common/extensions/api/types.json
@@ -12,7 +12,7 @@
         "type": "object",
         "js_module": "ChromeSetting",
         "customBindings": "ChromeSetting",
-        "description": "An interface that allows access to a Chrome browser setting. See $ref:proxy.settings for an example.",
+        "description": "An interface that allows access to a Chrome browser setting. See $(ref:proxy.settings) for an example.",
         "functions": [
           {
             "name": "get",
diff --git a/chrome/common/extensions/api/webview_tag.json b/chrome/common/extensions/api/webview_tag.json
index cfbe2fe..0521853 100644
--- a/chrome/common/extensions/api/webview_tag.json
+++ b/chrome/common/extensions/api/webview_tag.json
@@ -350,7 +350,7 @@
       {
         "name": "isUserAgentOverridden",
         "type": "function",
-        "description": "Indicates whether or not the webview's user agent string has been overridden by $ref:setUserAgentOverride"
+        "description": "Indicates whether or not the webview's user agent string has been overridden by $(ref:webviewTag.setUserAgentOverride)"
       },
       {
         "name": "reload",
@@ -607,7 +607,7 @@
             "name": "request",
             "type": "object",
             "properties": {},
-            "description": "An object which holds details of the requested permission. Depending on the type of permission requested, this may be a $ref:MediaPermissionRequest, $ref:GeolocationPermissionRequest, $ref:PointerLockPermissionRequest, $ref:DownloadPermissionRequest, or $ref:LoadPluginPermissionRequest."
+            "description": "An object which holds details of the requested permission. Depending on the type of permission requested, this may be a $(ref:webviewTag.MediaPermissionRequest), $(ref:webviewTag.GeolocationPermissionRequest), $(ref:webviewTag.PointerLockPermissionRequest), $(ref:webviewTag.DownloadPermissionRequest), or $(ref:webviewTag.LoadPluginPermissionRequest)."
           }
         ]
       },
diff --git a/chrome/common/extensions/api/windows.json b/chrome/common/extensions/api/windows.json
index 8ef02ac..00ded38 100644
--- a/chrome/common/extensions/api/windows.json
+++ b/chrome/common/extensions/api/windows.json
@@ -14,28 +14,28 @@
         "id": "Window",
         "type": "object",
         "properties": {
-          "id": {"type": "integer", "optional": true, "minimum": 0, "description": "The ID of the window. Window IDs are unique within a browser session. Under some circumstances a Window may not be assigned an ID, for example when querying windows using the $ref:sessions API, in which case a session ID may be present."},
+          "id": {"type": "integer", "optional": true, "minimum": 0, "description": "The ID of the window. Window IDs are unique within a browser session. Under some circumstances a Window may not be assigned an ID, for example when querying windows using the $(ref:sessions) API, in which case a session ID may be present."},
           "focused": {"type": "boolean", "description": "Whether the window is currently the focused window."},
-          "top": {"type": "integer", "optional": true, "description": "The offset of the window from the top edge of the screen in pixels. Under some circumstances a Window may not be assigned top property, for example when querying closed windows from the $ref:sessions API."},
-          "left": {"type": "integer", "optional": true, "description": "The offset of the window from the left edge of the screen in pixels. Under some circumstances a Window may not be assigned left property, for example when querying closed windows from the $ref:sessions API."},
-          "width": {"type": "integer", "optional": true, "description": "The width of the window, including the frame, in pixels. Under some circumstances a Window may not be assigned width property, for example when querying closed windows from the $ref:sessions API."},
-          "height": {"type": "integer", "optional": true, "description": "The height of the window, including the frame, in pixels. Under some circumstances a Window may not be assigned height property, for example when querying closed windows from the $ref:sessions API."},
-          "tabs": {"type": "array", "items": { "$ref": "tabs.Tab" }, "optional": true, "description": "Array of $ref:tabs.Tab objects representing the current tabs in the window."},
+          "top": {"type": "integer", "optional": true, "description": "The offset of the window from the top edge of the screen in pixels. Under some circumstances a Window may not be assigned top property, for example when querying closed windows from the $(ref:sessions) API."},
+          "left": {"type": "integer", "optional": true, "description": "The offset of the window from the left edge of the screen in pixels. Under some circumstances a Window may not be assigned left property, for example when querying closed windows from the $(ref:sessions) API."},
+          "width": {"type": "integer", "optional": true, "description": "The width of the window, including the frame, in pixels. Under some circumstances a Window may not be assigned width property, for example when querying closed windows from the $(ref:sessions) API."},
+          "height": {"type": "integer", "optional": true, "description": "The height of the window, including the frame, in pixels. Under some circumstances a Window may not be assigned height property, for example when querying closed windows from the $(ref:sessions) API."},
+          "tabs": {"type": "array", "items": { "$ref": "tabs.Tab" }, "optional": true, "description": "Array of $(ref:tabs.Tab) objects representing the current tabs in the window."},
           "incognito": {"type": "boolean", "description": "Whether the window is incognito."},
           "type": {
             "type": "string",
             "optional": true,
-            "description": "The type of browser window this is. Under some circumstances a Window may not be assigned type property, for example when querying closed windows from the $ref:sessions API.",
+            "description": "The type of browser window this is. Under some circumstances a Window may not be assigned type property, for example when querying closed windows from the $(ref:sessions) API.",
             "enum": ["normal", "popup", "panel", "app"]
           },
           "state": {
             "type": "string",
             "optional": true,
-            "description": "The state of this browser window. Under some circumstances a Window may not be assigned state property, for example when querying closed windows from the $ref:sessions API.",
+            "description": "The state of this browser window. Under some circumstances a Window may not be assigned state property, for example when querying closed windows from the $(ref:sessions) API.",
             "enum": ["normal", "minimized", "maximized", "fullscreen"]
           },
           "alwaysOnTop": {"type": "boolean", "description": "Whether the window is set to be always on top."},
-          "sessionId": {"type": "string", "optional": true, "description": "The session ID used to uniquely identify a Window obtained from the $ref:sessions API."}
+          "sessionId": {"type": "string", "optional": true, "description": "The session ID used to uniquely identify a Window obtained from the $(ref:sessions) API."}
         }
       }
     ],
@@ -62,7 +62,7 @@
             "optional": true,
             "description": "",
             "properties": {
-              "populate": {"type": "boolean", "optional": true, "description": "If true, the $ref:windows.Window object will have a <var>tabs</var> property that contains a list of the $ref:tabs.Tab objects. The <code>Tab</code> objects only contain the <code>url</code>, <code>title</code> and <code>favIconUrl</code> properties if the extension's manifest file includes the <code>\"tabs\"</code> permission." }
+              "populate": {"type": "boolean", "optional": true, "description": "If true, the $(ref:windows.Window) object will have a <var>tabs</var> property that contains a list of the $(ref:tabs.Tab) objects. The <code>Tab</code> objects only contain the <code>url</code>, <code>title</code> and <code>favIconUrl</code> properties if the extension's manifest file includes the <code>\"tabs\"</code> permission." }
             }
           },
           {
@@ -87,7 +87,7 @@
             "optional": true,
             "description": "",
             "properties": {
-              "populate": {"type": "boolean", "optional": true, "description": "If true, the $ref:windows.Window object will have a <var>tabs</var> property that contains a list of the $ref:tabs.Tab objects. The <code>Tab</code> objects only contain the <code>url</code>, <code>title</code> and <code>favIconUrl</code> properties if the extension's manifest file includes the <code>\"tabs\"</code> permission." }
+              "populate": {"type": "boolean", "optional": true, "description": "If true, the $(ref:windows.Window) object will have a <var>tabs</var> property that contains a list of the $(ref:tabs.Tab) objects. The <code>Tab</code> objects only contain the <code>url</code>, <code>title</code> and <code>favIconUrl</code> properties if the extension's manifest file includes the <code>\"tabs\"</code> permission." }
             }
           },
           {
@@ -112,7 +112,7 @@
             "optional": true,
             "description": "",
             "properties": {
-              "populate": {"type": "boolean", "optional": true, "description": "If true, the $ref:windows.Window object will have a <var>tabs</var> property that contains a list of the $ref:tabs.Tab objects. The <code>Tab</code> objects only contain the <code>url</code>, <code>title</code> and <code>favIconUrl</code> properties if the extension's manifest file includes the <code>\"tabs\"</code> permission." }
+              "populate": {"type": "boolean", "optional": true, "description": "If true, the $(ref:windows.Window) object will have a <var>tabs</var> property that contains a list of the $(ref:tabs.Tab) objects. The <code>Tab</code> objects only contain the <code>url</code>, <code>title</code> and <code>favIconUrl</code> properties if the extension's manifest file includes the <code>\"tabs\"</code> permission." }
             }
           },
           {
@@ -137,7 +137,7 @@
             "optional": true,
             "description": "",
             "properties": {
-              "populate": {"type": "boolean", "optional": true, "description": "If true, each $ref:windows.Window object will have a <var>tabs</var> property that contains a list of the $ref:tabs.Tab objects for that window. The <code>Tab</code> objects only contain the <code>url</code>, <code>title</code> and <code>favIconUrl</code> properties if the extension's manifest file includes the <code>\"tabs\"</code> permission." }
+              "populate": {"type": "boolean", "optional": true, "description": "If true, each $(ref:windows.Window) object will have a <var>tabs</var> property that contains a list of the $(ref:tabs.Tab) objects for that window. The <code>Tab</code> objects only contain the <code>url</code>, <code>title</code> and <code>favIconUrl</code> properties if the extension's manifest file includes the <code>\"tabs\"</code> permission." }
             }
           },
           {
diff --git a/chrome/common/extensions/docs/server2/app.yaml b/chrome/common/extensions/docs/server2/app.yaml
index b3522d7..29b5aa7 100644
--- a/chrome/common/extensions/docs/server2/app.yaml
+++ b/chrome/common/extensions/docs/server2/app.yaml
@@ -1,5 +1,5 @@
 application: chrome-apps-doc
-version: 3-1-1
+version: 3-2-0
 runtime: python27
 api_version: 1
 threadsafe: false
diff --git a/chrome/common/extensions/docs/server2/cron.yaml b/chrome/common/extensions/docs/server2/cron.yaml
index 71af8b8..72ebc6f 100644
--- a/chrome/common/extensions/docs/server2/cron.yaml
+++ b/chrome/common/extensions/docs/server2/cron.yaml
@@ -2,4 +2,4 @@ cron:
 - description: Repopulates all cached data.
   url: /_cron
   schedule: every 5 minutes
-  target: 3-1-1
+  target: 3-2-0
diff --git a/chrome/common/extensions/docs/server2/document_renderer.py b/chrome/common/extensions/docs/server2/document_renderer.py
index e4621ea..8aa7380 100644
--- a/chrome/common/extensions/docs/server2/document_renderer.py
+++ b/chrome/common/extensions/docs/server2/document_renderer.py
@@ -2,13 +2,16 @@
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 
+import logging
+import os
 from document_parser import ParseDocument
+from third_party.json_schema_compiler.model import UnixName
 
 
 class DocumentRenderer(object):
-  '''Performs document-level rendering such as the title and table of contents:
-  pulling that data out of the document, then replacing the $(title) and
-  $(table_of_contents) tokens with them.
+  '''Performs document-level rendering such as the title, references,
+  and table of contents: pulling that data out of the document, then
+  replacing the $(title), $(ref:...) and $(table_of_contents) tokens with them.
 
   This can be thought of as a parallel to TemplateRenderer; while
   TemplateRenderer is responsible for interpreting templates and rendering files
@@ -18,10 +21,64 @@ class DocumentRenderer(object):
   the concept. Currently title and table_of_contents are supported.
   '''
 
-  def __init__(self, table_of_contents_renderer):
+  def __init__(self, table_of_contents_renderer, ref_resolver):
     self._table_of_contents_renderer = table_of_contents_renderer
+    self._ref_resolver = ref_resolver
+
+  def _RenderLinks(self, document, path):
+    ''' Replaces all $(ref:...) references in |document| with html links
+    '''
+    START_REF = '$(ref:'
+    END_REF = ')'
+    MAX_REF_LENGTH = 100
+
+    new_document = []
+
+    # Keeps track of position within |document|
+    cursor_index = 0
+    start_ref_index = document.find(START_REF)
+
+    while start_ref_index != -1:
+      end_ref_index = document.find(END_REF, start_ref_index)
+
+      if (end_ref_index == -1 or
+          end_ref_index - start_ref_index > MAX_REF_LENGTH):
+        end_ref_index = document.find(' ', start_ref_index)
+        logging.error('%s:%s has no terminating ) at line %s' % (
+            path,
+            document[start_ref_index:end_ref_index],
+            document.count('\n', 0, end_ref_index)))
+
+        new_document.append(document[cursor_index:end_ref_index + 1])
+      else:
+        ref = document[start_ref_index:end_ref_index]
+        ref_parts = ref[len(START_REF):].split(' ', 1)
+
+        # Guess the api name from the html name, replacing '_' with '.' (e.g.
+        # if the page is app_window.html, guess the api name is app.window)
+        api_name = os.path.splitext(os.path.basename(path))[0].replace('_', '.')
+        title = ref_parts[0] if len(ref_parts) == 1 else ref_parts[1]
+
+        ref_dict = self._ref_resolver.SafeGetLink(ref_parts[0],
+                                                  namespace=api_name,
+                                                  title=title)
+
+        new_document.append(document[cursor_index:start_ref_index])
+        new_document.append('<a href=%s>%s</a>' % (ref_dict['href'],
+                                                   ref_dict['text']))
+
+      cursor_index = end_ref_index + 1
+      start_ref_index = document.find(START_REF, cursor_index)
+
+    new_document.append(document[cursor_index:])
+
+    return ''.join(new_document)
+
+  def Render(self, document, path, render_title=False):
+    # Render links first so that parsing and later replacements aren't
+    # affected by $(ref...) substitutions
+    document = self._RenderLinks(document, path)
 
-  def Render(self, document, render_title=False):
     parsed_document = ParseDocument(document, expect_title=render_title)
     toc_text, toc_warnings = self._table_of_contents_renderer.Render(
         parsed_document.sections)
diff --git a/chrome/common/extensions/docs/server2/document_renderer_test.py b/chrome/common/extensions/docs/server2/document_renderer_test.py
index 167bd30..7f7ff1f 100755
--- a/chrome/common/extensions/docs/server2/document_renderer_test.py
+++ b/chrome/common/extensions/docs/server2/document_renderer_test.py
@@ -18,51 +18,107 @@ class DocumentRendererUnittest(unittest.TestCase):
 
   def testNothingToSubstitute(self):
     document = 'hello world'
+    path = 'some/path/to/document.html'
 
-    text, warnings = self._renderer.Render(document)
+    text, warnings = self._renderer.Render(document, path)
     self.assertEqual(document, text)
     self.assertEqual([], warnings)
 
-    text, warnings = self._renderer.Render(document, render_title=True)
+    text, warnings = self._renderer.Render(document, path, render_title=True)
     self.assertEqual(document, text)
     self.assertEqual(['Expected a title'], warnings)
 
   def testTitles(self):
     document = '<h1>title</h1> then $(title) then another $(title)'
+    path = 'some/path/to/document.html'
 
-    text, warnings = self._renderer.Render(document)
+    text, warnings = self._renderer.Render(document, path)
     self.assertEqual(document, text)
     self.assertEqual(['Found unexpected title "title"'], warnings)
 
-    text, warnings = self._renderer.Render(document, render_title=True)
+    text, warnings = self._renderer.Render(document, path, render_title=True)
     self.assertEqual('<h1>title</h1> then title then another $(title)', text)
     self.assertEqual([], warnings)
 
   def testTocs(self):
     document = ('here is a toc $(table_of_contents) '
                 'and another $(table_of_contents)')
-    expected_document = ('here is a toc <table-of-contents> '
-                         'and another $(table_of_contents)')
+    expected_document = ('here is a toc <table-of-contents> and another '
+                         '$(table_of_contents)')
+    path = 'some/path/to/document.html'
 
-    text, warnings = self._renderer.Render(document)
+    text, warnings = self._renderer.Render(document, path)
     self.assertEqual(expected_document, text)
     self.assertEqual([], warnings)
 
-    text, warnings = self._renderer.Render(document, render_title=True)
+    text, warnings = self._renderer.Render(document, path, render_title=True)
+    self.assertEqual(expected_document, text)
+    self.assertEqual(['Expected a title'], warnings)
+
+  def testRefs(self):
+    # The references in this and subsequent tests won't actually be resolved
+    document = 'A ref $(ref:baz.baz_e1) here, $(ref:foo.foo_t3 ref title) there'
+    expected_document = ('A ref <a href=#type-baz_e1>baz.baz_e1</a> '
+                         'here, <a href=#type-foo_t3>ref title</a> '
+                         'there')
+    path = 'some/path/to/document.html'
+
+    text, warnings = self._renderer.Render(document, path)
+    self.assertEqual(expected_document, text)
+    self.assertEqual([], warnings)
+
+    text, warnings = self._renderer.Render(document, path, render_title=True)
     self.assertEqual(expected_document, text)
     self.assertEqual(['Expected a title'], warnings)
 
   def testTitleAndToc(self):
     document = '<h1>title</h1> $(title) and $(table_of_contents)'
+    path = 'some/path/to/document.html'
 
-    text, warnings = self._renderer.Render(document)
+    text, warnings = self._renderer.Render(document, path)
     self.assertEqual('<h1>title</h1> $(title) and <table-of-contents>', text)
     self.assertEqual(['Found unexpected title "title"'], warnings)
 
-    text, warnings = self._renderer.Render(document, render_title=True)
+    text, warnings = self._renderer.Render(document, path, render_title=True)
     self.assertEqual('<h1>title</h1> title and <table-of-contents>', text)
     self.assertEqual([], warnings)
 
+  def testRefInTitle(self):
+    document = '<h1>$(ref:baz.baz_e1 title)</h1> A $(title) was here'
+    expected_document_no_title = ('<h1><a href=#type-baz_e1>'
+                                  'title</a></h1> A $(title) was here')
+
+    expected_document = ('<h1><a href=#type-baz_e1>title</a></h1>'
+                         ' A title was here')
+    path = 'some/path/to/document.html'
+
+    text, warnings = self._renderer.Render(document, path)
+    self.assertEqual(expected_document_no_title, text)
+    self.assertEqual([('Found unexpected title "title"')], warnings)
+
+    text, warnings = self._renderer.Render(document, path, render_title=True)
+    self.assertEqual(expected_document, text)
+    self.assertEqual([], warnings)
+
+  def testInvalidRef(self):
+    # There needs to be more than 100 characters between the invalid ref
+    # and the next ref
+    document = ('An invalid $(ref:foo.foo_t3 a title with some long '
+                'text containing a valid reference pointing to '
+                '$(ref:baz.baz_e1) here')
+    expected_document = ('An invalid $(ref:foo.foo_t3 a title with some long '
+                         'text containing a valid reference pointing to <a'
+                         ' href=#type-baz_e1>baz.baz_e1</a> here')
+    path = 'some/path/to/document_api.html'
+
+    text, warnings = self._renderer.Render(document, path)
+    self.assertEqual(expected_document, text)
+    self.assertEqual([], warnings)
+
+    text, warnings = self._renderer.Render(document, path, render_title=True)
+    self.assertEqual(expected_document, text)
+    self.assertEqual(['Expected a title'], warnings)
+
 
 if __name__ == '__main__':
   unittest.main()
diff --git a/chrome/common/extensions/docs/server2/render_servlet.py b/chrome/common/extensions/docs/server2/render_servlet.py
index 3391415..d6e81cb 100644
--- a/chrome/common/extensions/docs/server2/render_servlet.py
+++ b/chrome/common/extensions/docs/server2/render_servlet.py
@@ -97,6 +97,7 @@ class RenderServlet(Servlet):
       # HACK: the Google ID thing (google2ed...) doesn't have a title.
       content, doc_warnings = server_instance.document_renderer.Render(
           template_content,
+          path,
           render_title=path != 'google2ed1af765c529f57.html')
       warnings = template_warnings + doc_warnings
       if warnings:
diff --git a/chrome/common/extensions/docs/server2/server_instance.py b/chrome/common/extensions/docs/server2/server_instance.py
index 7dd7db0..771d68e 100644
--- a/chrome/common/extensions/docs/server2/server_instance.py
+++ b/chrome/common/extensions/docs/server2/server_instance.py
@@ -151,10 +151,11 @@ class ServerInstance(object):
     # TODO(kalman): It may be better for |document_renderer| to construct a
     # TemplateDataSource itself rather than depending on template_renderer, but
     # for that the above todo should be addressed.
-    self.document_renderer = DocumentRenderer(TableOfContentsRenderer(
-        host_fs_at_trunk,
-        compiled_fs_factory,
-        self.template_renderer))
+    self.document_renderer = DocumentRenderer(
+        TableOfContentsRenderer(host_fs_at_trunk,
+                                compiled_fs_factory,
+                                self.template_renderer),
+        self.ref_resolver_factory.Create())
 
   @staticmethod
   def ForTest(file_system=None, file_system_provider=None, base_path='/'):
diff --git a/chrome/common/extensions/docs/server2/test_data/canned_data.py b/chrome/common/extensions/docs/server2/test_data/canned_data.py
index 70bdb0e..efb89b7 100644
--- a/chrome/common/extensions/docs/server2/test_data/canned_data.py
+++ b/chrome/common/extensions/docs/server2/test_data/canned_data.py
@@ -99,7 +99,9 @@ CANNED_TEST_FILE_SYSTEM_DATA = MoveTo(EXTENSIONS, {
               }
             ]
           }
-        })
+        }),
+        'manifest.json': '{}',
+        'permissions.json': '{}'
       },
       'private': {
         'intro_tables': {