Reduces friction for CUJ "I want to know about the supported manifest keys"

site/en/_partials/extensions/reusing-prod-extension-id.md

@@ -1,4 +1,4 @@
-## Keep a consistent extension ID {: #keep-consistent-id }
+## Keeping a consistent extension ID {: #keep-consistent-id }
 
 Preserving a single ID is essential during development. To keep a consistent ID, follow these steps:
 

site/en/docs/extensions/mv3/manifest/default_locale/index.md

@@ -6,8 +6,13 @@ updated: 2018-04-26
 description: Reference documentation for the default_locale property of manifest.json.
 ---
 
-Specifies the subdirectory of `_locales` that contains the default strings for this extension. This
-field is **required** in extensions that have a `_locales` directory; it **must be absent** in
-extensions that have no `_locales` directory. For details, see [Internationalization][1].
+Defines the default language of an extension that supports multiple locales. It is the name of the subdirectory in `_locales` that contains the default language for this extension. For example, the following code indicates that English is the default language:
 
-[1]: /docs/extensions/i18n
+```json
+"default_locale": "en"
+```
+
+This field is **required** for localized extensions (those with a `_locales` directory), but **must be absent** in
+extensions that have no `_locales` directory. For details, see [Internationalization][api-i18n].
+
+[api-i18n]: /docs/extensions/i18n

site/en/docs/extensions/mv3/manifest/description/index.md

@@ -7,9 +7,15 @@ description: Reference documentation for the description property of manifest.js
 ---
 
 A plain text string (no HTML or other formatting; no more than 132 characters) that describes the
-extension. The description should be suitable for both the browser's extension management UI and the
-[Chrome Web Store][1]. You can specify locale-specific strings for this field; see
-[Internationalization][2] for details.
+extension. For example:
 
-[1]: https://chrome.google.com/webstore
-[2]: /docs/extensions/i18n
+```json
+"description": "A description of my extension"
+```
+
+The description should be suitable for both the browser's Extensions page (chrome://extensions) and the
+[Chrome Web Store][cws]. You can specify locale-specific strings for this field; see
+[Internationalization][api-i18n] for details.
+
+[cws]: https://chrome.google.com/webstore
+[api-i18n]: /docs/extensions/i18n

site/en/docs/extensions/mv3/manifest/externally_connectable/index.md

@@ -1,22 +1,21 @@
 ---
-layout: "layouts/doc-post.njk"
-title: "externally_connectable"
+layout: 'layouts/doc-post.njk'
+title: 'externally_connectable'
 date: 2013-08-21
 updated: 2014-10-31
 description: Reference documentation for the externally_connectable property of manifest.json.
 ---
 
-The `externally_connectable` manifest property declares which extensions, apps, and web pages can
-connect to your extension via [runtime.connect][1] and [runtime.sendMessage][2].
+The `externally_connectable` manifest property declares which extensions and web pages can
+connect to your extension via [runtime.connect][runtime-connect] and [runtime.sendMessage][runtime-sendmessage].
 
-For a tutorial on message passing see [cross-extension and app messaging][3] and [sending messages
-from web pages][4].
+For a tutorial on message passing see [cross-extension messaging][messages-other-exts] and [sending messages
+from web pages][messages-webpage].
 
 ## Connecting without externally_connectable {: #without-externally-connectable }
 
-If `externally_connectable` is not declared in your extension's manifest, all extensions and apps
-can connect, but no webpages can connect. As a consequence, when updating your manifest to use
-`externally_connectable`, if `"ids": ["*"]` is not specified then other extensions and apps will
+If the `externally_connectable` key is **_not_** declared in your extension's manifest, all extensions can connect, but no webpages can connect. As a consequence, when updating your manifest to use
+`externally_connectable`, if `"ids": ["*"]` is not specified then other extensions will
 lose the ability to connect to your extension. This may be an unintended consequence, so keep it in
 mind.
 
@@ -26,28 +25,17 @@ mind.
 {
   "name": "My externally connectable extension",
   "externally_connectable": {
-    // Extension and app IDs. If this field is not specified, no
-    // extensions or apps can connect.
     "ids": [
       "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
       "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
       ...
-      // Alternatively, to match all extensions and apps, specify only
-      // "*".
-      "*"
     ],
-    // Match patterns for web pages. Does not affect content scripts.
     // If this field is not specified, no webpages can connect.
     "matches": [
       "https://*.google.com/*",
       "*://*.chromium.org/*",
       ...
     ],
-    // Indicates that the extension would like to make use of the TLS
-    // channel ID of the web page connecting to it. The web page must
-    // also opt to send the TLS channel ID to the extension via setting
-    // includeTlsChannelId to true in runtime.connect's connectInfo
-    // or runtime.sendMessage's options.
     "accepts_tls_channel_id": false
   },
   ...
@@ -56,38 +44,32 @@ mind.
 
 ## Reference {: #reference }
 
-The externally_connectable manifest key can have the following properties:
+The `"externally_connectable"` manifest key includes the following _optional_ properties:
 
-- **`ids` (array of string)** - optional
+`"ids"`
+: The IDs of extensions that are allowed to connect. If left empty or unspecified, no extensions or apps can connect. The wildcard `"*"` will allow all extensions and apps to connect.
 
-  The IDs of extensions or apps that are allowed to connect. If left empty or unspecified, no
-  extensions or apps can connect.
+`"matches"`
+: The URL patterns for _web pages_ that are allowed to connect. If left empty or unspecified, no web pages can connect. Patterns cannot include wildcard domains nor subdomains of [(effective) top level domains][public-suffix], for example:
 
-  The wildcard `"*"` will allow all extensions and apps to connect.
+| ✅ Valid URLs              | ❌ Invalid URLs        |
+|---------------------------|-----------------------|
+| `*://example.com/`       | `*://example.com/one/` |
+| `http://*.example.org/*` | `<all_urls>`          |
+| `https://example.com/*`  | `http://*/*`          |
 
-- **`matches` (array of string)** - optional
+`"accepts_tls_channel_id"`
+: Enables the extension to make use of the TLS channel ID of the web page connecting to it. The web page must also opt to send the [TLS channel ID][runtime-tls-channel] to the extension via setting
+`includeTlsChannelId` to `true` in runtime.connect's [connectInfo][connect-include-tls] or runtime.sendMessage's [options][options-include-tls]. If set to `false`,
+[runtime.MessageSender.tlsChannelId][runtime-tls-channel] will never be set under any circumstance.
 
-  The URL patterns for _web pages_ that are allowed to connect. _This does not affect content
-  scripts._ If left empty or unspecified, no web pages can connect.
+This does not affect content scripts.
 
-  Patterns cannot include wildcard domains nor subdomains of [(effective) top level domains][7];
-  `*://google.com/*` and `http://*.chromium.org/*` are valid, while `<all_urls>`, `http://*/*`,
-  `*://*.com/*`, and even `http://*.appspot.com/*` are not.
-
-- **`accepts_tls_channel_id` (boolean)** - optional
-
-  If `true`, messages sent via [runtime.connect][8] or [runtime.sendMessage][9] will set
-  [runtime.MessageSender.tlsChannelId][10] if those methods request it to be. If `false`,
-  [runtime.MessageSender.tlsChannelId][11] will never be set under any circumstance.
-
-[1]: /docs/extensions/runtime#method-connect
-[2]: /docs/extensions/runtime#method-sendMessage
-[3]: /docs/extensions/mv3/messaging#external
-[4]: /docs/extensions/mv3/messaging#external-webpage
-[5]: /docs/extensions/runtime#method-connect
-[6]: /docs/extensions/runtime#method-sendMessage
-[7]: http://publicsuffix.org/list/
-[8]: /docs/extensions/runtime#method-connect
-[9]: /docs/extensions/runtime#method-sendMessage
-[10]: /docs/extensions/runtime#property-MessageSender-tlsChannelId
-[11]: /docs/extensions/runtime#property-MessageSender-tlsChannelId
+[connect-include-tls]: /docs/extensions/reference/runtime/#type-connect-connectInfo
+[messages-other-ext]: /docs/extensions/mv3/messaging#external
+[messages-webpage]: /docs/extensions/mv3/messaging#external-webpage
+[options-include-tls]: /docs/extensions/reference/runtime/#property-sendMessage-options-includeTlsChannelId
+[public-suffix]: http://publicsuffix.org/list/
+[runtime-connect]: /docs/extensions/reference/runtime#method-connect
+[runtime-sendmessage]: /docs/extensions/reference/runtime#method-sendMessage
+[runtime-tls-channel]: /docs/extensions/runtime#property-MessageSender-tlsChannelId

site/en/docs/extensions/mv3/manifest/icons/index.md

@@ -34,8 +34,7 @@ Here's an example of how to declare the icons in the manifest:
 {% Aside %}
 
 You may provide icons of any other size you wish, and Chrome will attempt to use the best size where
-appropriate. For example, Windows often requires 32-pixel icons, and if the app includes a 32-pixel
-icon, Chrome will choose that instead of shrinking a 48-pixel icon.
+appropriate. 
 
 {% endAside %}