Documentation v2

extension-js · Sep 11, 2024 · 34d9b8f · 34d9b8f
1 parent 164623f
commit 34d9b8f
Show file tree

Hide file tree

Showing 54 changed files with 77 additions and 96 deletions.
diff --git a/_WIP_Configuration Files/_Webpack.md b/_WIP_Configuration Files/_Webpack.md
diff --git a/_WIP_Features/The Manifest File.md b/_WIP_Features/The Manifest File.md
diff --git a/_WIP_Features/Migrating Your Extension.md → _WIP_Migrate/Migrating Your Extension.md b/_WIP_Features/Migrating Your Extension.md → _WIP_Migrate/Migrating Your Extension.md
diff --git a/docs/en/docs/_meta.json b/docs/en/docs/_meta.json
@@ -10,7 +10,22 @@
   },
   {
     "type": "dir",
-    "name": "guides",
-    "label": "Guides"
+    "name": "features",
+    "label": "Features"
+  },
+  {
+    "type": "dir",
+    "name": "languages-and-frameworks",
+    "label": "Languages and Frameworks"
+  },
+  {
+    "type": "dir",
+    "name": "api-support",
+    "label": "API Support"
+  },
+  {
+    "type": "dir",
+    "name": "commands",
+    "label": "Commands Reference"
   }
 ]
diff --git a/_WIP_Features/API Resolution.md → docs/en/docs/api-support/api-resolver.mdx b/_WIP_Features/API Resolution.md → docs/en/docs/api-support/api-resolver.mdx
diff --git a/_WIP_Features/HTML Fields.md → docs/en/docs/api-support/html.mdx b/_WIP_Features/HTML Fields.md → docs/en/docs/api-support/html.mdx
diff --git a/_WIP_Features/Icon Fields.md → docs/en/docs/api-support/icons.mdx b/_WIP_Features/Icon Fields.md → docs/en/docs/api-support/icons.mdx
diff --git a/_WIP_Features/JSON Fields.md → docs/en/docs/api-support/json.mdx b/_WIP_Features/JSON Fields.md → docs/en/docs/api-support/json.mdx
diff --git a/_WIP_Features/Locales Files.md → docs/en/docs/api-support/locales.mdx b/_WIP_Features/Locales Files.md → docs/en/docs/api-support/locales.mdx
diff --git a/...t/manifest-json/manifest-capabilities.mdx → docs/en/docs/api-support/manifest.mdx b/...t/manifest-json/manifest-capabilities.mdx → docs/en/docs/api-support/manifest.mdx
@@ -18,7 +18,7 @@ Cross-browser manifest support is not something easy to think as well, so Extens
 
 Fields like the action page and browser page overrides runs in the context of an HTML page. Adding any of these fields to your package JSON will make your .html file an entrypoint for your extension.
 
-![New extension template](../../../../../../assets/guides/development/new-template.png)
+![New extension template](../../../../../assets/guides/development/new-template.png)
 
 > A new extension from Extension.
 
@@ -62,7 +62,7 @@ The `storage.managed_schema` property [indicates a file within the extension tha
 
 ### Scripts Fields
 
-![The background inspect window](../../../../../../assets/guides/development/service_worker.png)
+![The background inspect window](../../../../../assets/guides/development/service_worker.png)
 
 Support for both `background.scripts` (Manifest V2) and `background.service_worker` (Manifest V3). All scripts have [hot-module-replacement](https://webpack.js.org/concepts/hot-module-replacement/) support, except for `background.service_worker` (which is live-reloaded).
 

diff --git a/_WIP_Features/Script Fields.md → docs/en/docs/api-support/scripts.mdx b/_WIP_Features/Script Fields.md → docs/en/docs/api-support/scripts.mdx
diff --git a/_WIP_Features/Web Accessible Resources.md → .../api-support/web_accessible_resources.mdx b/_WIP_Features/Web Accessible Resources.md → .../api-support/web_accessible_resources.mdx
diff --git a/docs/en/docs/guides/commands/_meta.json → docs/en/docs/commands/_meta.json b/docs/en/docs/guides/commands/_meta.json → docs/en/docs/commands/_meta.json
diff --git a/docs/en/docs/guides/commands/build.mdx → docs/en/docs/commands/build.mdx b/docs/en/docs/guides/commands/build.mdx → docs/en/docs/commands/build.mdx
diff --git a/docs/en/docs/guides/commands/create.mdx → docs/en/docs/commands/create.mdx b/docs/en/docs/guides/commands/create.mdx → docs/en/docs/commands/create.mdx
diff --git a/docs/en/docs/guides/commands/dev.mdx → docs/en/docs/commands/dev.mdx b/docs/en/docs/guides/commands/dev.mdx → docs/en/docs/commands/dev.mdx
diff --git a/docs/en/docs/guides/commands/reference.mdx → docs/en/docs/commands/reference.mdx b/docs/en/docs/guides/commands/reference.mdx → docs/en/docs/commands/reference.mdx
diff --git a/docs/en/docs/guides/commands/start.mdx → docs/en/docs/commands/start.mdx b/docs/en/docs/guides/commands/start.mdx → docs/en/docs/commands/start.mdx
diff --git a/docs/en/docs/features/_meta.json b/docs/en/docs/features/_meta.json
diff --git a/docs/en/docs/features/browser-runners.mdx b/docs/en/docs/features/browser-runners.mdx
diff --git a/.../manifest-json/manifest-compatibility.mdx → ...ures/browser-specific-manifest-fields.mdx b/.../manifest-json/manifest-compatibility.mdx → ...ures/browser-specific-manifest-fields.mdx
@@ -6,7 +6,7 @@ In an ideal world, browser vendors would agree between conventions and developer
 
 ## Check For Required Fields
 
-![Required Field]((../../../../../../assets/guides/development/required_field.png)
+![Required Field]((../../../../../assets/guides/development/required_field.png)
 
 It is a common standard across all browsers vendors that the minimum Manifest file should contain a `name`, a `version`, and a `manifest_version` field as requirements. Missing one of these fields results in a runtime error.
 
@@ -16,6 +16,6 @@ Fields such as [`options_page`](https://developer.mozilla.org/en-US/docs/Mozilla
 
 ## Check For Invalid Field Types
 
-![Invalid Field]((../../../../../../assets/guides/development/invalid_field.png)
+![Invalid Field]((../../../../../assets/guides/development/invalid_field.png)
 
 While the [`action` page in Chrome](https://developer.chrome.com/docs/extensions/reference/api/action) accepts a `default_icon` field value as a string, per the [official Manifest JSON Schema](https://json.schemastore.org/chrome-manifest.json) it is expected to be an object in Manifest V3. Using invalid field types results in a warning message.
diff --git a/...des/development/environment-variables.mdx → ...n/docs/features/environment-variables.mdx b/...des/development/environment-variables.mdx → ...n/docs/features/environment-variables.mdx
@@ -5,9 +5,9 @@
 > [!warning]
 > This feature is not stable yet. You can track its development [here](https://github.com/cezaraugusto/extension/issues/40).
 
-Take for example, our ChatGPT $([Template](../../getting-started/templates)).
+Take for example, our ChatGPT $([Template](../getting-started/templates)).
 
-![ChatGPT Extension Template](../../../../../assets/guides/development/chatgpt-template.png)
+![ChatGPT Extension Template](../../../../assets/guides/development/chatgpt-template.png)
 
 See that it expects the `EXTENSION_OPENAI_API_KEY` environment variable? Create an `.env` file at the project root so Extension can parse its contents at runtime.
 

diff --git a/docs/en/docs/features/error-handling.mdx b/docs/en/docs/features/error-handling.mdx
@@ -0,0 +1,21 @@
+# Manifest Compatibility
+
+The manifest.json file is the only required file in an extension. While very similar between browsers and versions, different versions and different browser vendors can have slightly different requirements between them.
+
+In an ideal world, browser vendors would agree between conventions and developers shouldn't worry about cross-browser compatibilities. While this doesn't happen, `Extension` has an ever growing support for the different manifest files across `manifest_version`s and browser vendors.
+
+## Check For Required Fields
+
+![Required Field]((../../../../../assets/guides/development/required_field.png)
+
+It is a common standard across all browsers vendors that the minimum Manifest file should contain a `name`, a `version`, and a `manifest_version` field as requirements. Missing one of these fields results in a runtime error.
+
+## Check For Deprecated Fields
+
+Fields such as [`options_page`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_page) are deprecated in current valid Manifest versions. ~~Using deprecated fields results in a runtime error~~. [This feature is being tracked for future implementation](https://github.com/cezaraugusto/extension/issues/43).
+
+## Check For Invalid Field Types
+
+![Invalid Field]((../../../../../assets/guides/development/invalid_field.png)
+
+While the [`action` page in Chrome](https://developer.chrome.com/docs/extensions/reference/api/action) accepts a `default_icon` field value as a string, per the [official Manifest JSON Schema](https://json.schemastore.org/chrome-manifest.json) it is expected to be an object in Manifest V3. Using invalid field types results in a warning message.
diff --git a/docs/en/docs/features/extension-packaging.mdx b/docs/en/docs/features/extension-packaging.mdx
diff --git a/docs/en/docs/features/extension.config.js.mdx b/docs/en/docs/features/extension.config.js.mdx
diff --git a/docs/en/docs/features/polyfill.mdx b/docs/en/docs/features/polyfill.mdx
@@ -0,0 +1,21 @@
+# Manifest Compatibility
+
+The manifest.json file is the only required file in an extension. While very similar between browsers and versions, different versions and different browser vendors can have slightly different requirements between them.
+
+In an ideal world, browser vendors would agree between conventions and developers shouldn't worry about cross-browser compatibilities. While this doesn't happen, `Extension` has an ever growing support for the different manifest files across `manifest_version`s and browser vendors.
+
+## Check For Required Fields
+
+![Required Field]((../../../../../assets/guides/development/required_field.png)
+
+It is a common standard across all browsers vendors that the minimum Manifest file should contain a `name`, a `version`, and a `manifest_version` field as requirements. Missing one of these fields results in a runtime error.
+
+## Check For Deprecated Fields
+
+Fields such as [`options_page`](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/options_page) are deprecated in current valid Manifest versions. ~~Using deprecated fields results in a runtime error~~. [This feature is being tracked for future implementation](https://github.com/cezaraugusto/extension/issues/43).
+
+## Check For Invalid Field Types
+
+![Invalid Field]((../../../../../assets/guides/development/invalid_field.png)
+
+While the [`action` page in Chrome](https://developer.chrome.com/docs/extensions/reference/api/action) accepts a `default_icon` field value as a string, per the [official Manifest JSON Schema](https://json.schemastore.org/chrome-manifest.json) it is expected to be an object in Manifest V3. Using invalid field types results in a warning message.
diff --git a/_WIP_Features/Page Reload And HMR.md → docs/en/docs/features/reload.mdx b/_WIP_Features/Page Reload And HMR.md → docs/en/docs/features/reload.mdx
diff --git a/...cs/guides/development/special-folders.mdx → docs/en/docs/features/special-folders.mdx b/...cs/guides/development/special-folders.mdx → docs/en/docs/features/special-folders.mdx
@@ -16,7 +16,7 @@ Special folders are folders that allows you to work with files outside the scope
 
 To work with complementary HTML files (such as internal page links or `<iframe>`s), add the file into a `pages/` folder.
 
-![Pages Folder](../../../../../assets/guides/development/pages-folder2.png)
+![Pages Folder](../../../../assets/guides/development/pages-folder2.png)
 
 **Example:**
 An iframe as a sandboxed frame. [See the sandbox sample from Chrome Samples repository](https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/api-samples/sandbox/sandbox). The iframe is likely to be edited several times during development, so adding it inside a `pages/` folder guarantees support for hot page reloads and full integration with JavaScript/CSS pre/post-processors.
@@ -25,7 +25,7 @@ An iframe as a sandboxed frame. [See the sandbox sample from Chrome Samples repo
 
 For scripts without the need of HTML files, add the file into a `scripts/` folder. Any JavaScript-like file in this folder is a valid entry point.
 
-![Scripts Folder](../../../../../assets/guides/development/scripts-folder.png)
+![Scripts Folder](../../../../assets/guides/development/scripts-folder.png)
 
 **Example:**
 
@@ -37,11 +37,11 @@ For files that you don't want Extension to parse, or if you want a predictable o
 
 See thee example below using the previous [sandbox sample from Chrome Samples repository](https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/api-samples/sandbox/sandbox). `handlebars.js` is an external lib that we don't want to parse, so we add it to the `/public` path, and `Extension` will output the file as-is, skipping the compilation process.
 
-![Public Folder](../../../../../assets/guides/development/public-folder.png)
+![Public Folder](../../../../assets/guides/development/public-folder.png)
 
 ## Next Steps
 
-- Check the different types of [Templates](../../getting-started/templates) to bootstrap your next extension.
+- Check the different types of [Templates](../getting-started/templates) to bootstrap your next extension.
 - Learn more about how `Extension` handles [Manifest Compatibility Checker](./manifest-json/manifest-compatibility).
 
 ---
diff --git a/_WIP_Features/Static Assets.md → docs/en/docs/features/static.mdx b/_WIP_Features/Static Assets.md → docs/en/docs/features/static.mdx
diff --git a/docs/en/docs/guides/_meta.json b/docs/en/docs/guides/_meta.json
diff --git a/docs/en/docs/guides/development/manifest-json/_meta.json b/docs/en/docs/guides/development/manifest-json/_meta.json
diff --git a/docs/en/docs/guides/development/manifest-json/overview.mdx b/docs/en/docs/guides/development/manifest-json/overview.mdx
diff --git a/docs/en/docs/guides/development/modern-css/_meta.json b/docs/en/docs/guides/development/modern-css/_meta.json
diff --git a/docs/en/docs/guides/development/modern-css/less.mdx b/docs/en/docs/guides/development/modern-css/less.mdx
diff --git a/docs/en/docs/guides/development/modern-css/sass.mdx b/docs/en/docs/guides/development/modern-css/sass.mdx
diff --git a/docs/en/docs/guides/development/modern-javascript/_meta.json b/docs/en/docs/guides/development/modern-javascript/_meta.json
diff --git a/docs/en/docs/guides/development/_meta.json → .../docs/languages-and-frameworks/_meta.json b/docs/en/docs/guides/development/_meta.json → .../docs/languages-and-frameworks/_meta.json
@@ -1,9 +1,4 @@
 [
-  {
-    "type": "dir",
-    "name": "manifest-json",
-    "label": "Manifest JSON"
-  },
   {
     "type": "dir",
     "name": "modern-css",
@@ -15,12 +10,9 @@
     "label": "Modern JavaScript"
   },
   {
-    "name": "environment-variables",
-    "label": "Environment Variables"
-  },
-  {
-    "name": "special-folders",
-    "label": "Special Folders"
+    "type": "dir",
+    "name": "configuration",
+    "label": "Configuration"
   },
   {
     "name": "webassembly",

diff --git a/_WIP_Configuration Files/Babel.md → ...n/docs/languages-and-frameworks/babel.mdx b/_WIP_Configuration Files/Babel.md → ...n/docs/languages-and-frameworks/babel.mdx
diff --git a/...es/development/modern-css/css-modules.mdx → .../languages-and-frameworks/css-modules.mdx b/...es/development/modern-css/css-modules.mdx → .../languages-and-frameworks/css-modules.mdx
diff --git a/.../modern-javascript/ecmascript-modules.mdx → ...ges-and-frameworks/ecmascript-modules.mdx b/.../modern-javascript/ecmascript-modules.mdx → ...ges-and-frameworks/ecmascript-modules.mdx
diff --git a/_WIP_Configuration Files/_Eslint.md → .../docs/languages-and-frameworks/eslint.mdx b/_WIP_Configuration Files/_Eslint.md → .../docs/languages-and-frameworks/eslint.mdx
diff --git a/...nfiguration Files/_extension.config.js.md → ...es-and-frameworks/extension.config.js.mdx b/...nfiguration Files/_extension.config.js.md → ...es-and-frameworks/extension.config.js.mdx
diff --git a/_WIP_Development/_Modern CSS/Less.md → ...en/docs/languages-and-frameworks/less.mdx b/_WIP_Development/_Modern CSS/Less.md → ...en/docs/languages-and-frameworks/less.mdx
diff --git a/...uides/development/modern-css/overview.mdx → ...languages-and-frameworks/overview-css.mdx b/...uides/development/modern-css/overview.mdx → ...languages-and-frameworks/overview-css.mdx
diff --git a/...evelopment/modern-javascript/overview.mdx → ...ocs/languages-and-frameworks/overview.mdx b/...evelopment/modern-javascript/overview.mdx → ...ocs/languages-and-frameworks/overview.mdx
diff --git a/_WIP_Configuration Files/PostCSS.md → ...docs/languages-and-frameworks/postcss.mdx b/_WIP_Configuration Files/PostCSS.md → ...docs/languages-and-frameworks/postcss.mdx
diff --git a/docs/en/docs/languages-and-frameworks/preact.mdx b/docs/en/docs/languages-and-frameworks/preact.mdx
diff --git a/_WIP_Configuration Files/_Prettier.md → ...ocs/languages-and-frameworks/prettier.mdx b/_WIP_Configuration Files/_Prettier.md → ...ocs/languages-and-frameworks/prettier.mdx
diff --git a/...s/development/modern-javascript/react.mdx → ...n/docs/languages-and-frameworks/react.mdx b/...s/development/modern-javascript/react.mdx → ...n/docs/languages-and-frameworks/react.mdx
@@ -10,7 +10,7 @@ React is the library for web and native user interfaces.
 
 Extension comes with a default React template for new projects, which you can use as a starting point for your next React-based Extension. This is the easiest way to have React integrated with Extension.
 
-![React Extension Template](../../../../../../assets/guides/development/react-template.png)
+![React Extension Template](../../../../../assets/guides/development/react-template.png)
 
 ### Try it yourself
 
@@ -26,7 +26,7 @@ Extension comes with a default React template for new projects, which you can us
 
 Alternatively, `Extension` also supports a React+TypeScript template for a more robust UI.
 
-![React Extension Template](../../../../../../assets/guides/development/react-ts-template.png)
+![React Extension Template](../../../../../assets/guides/development/react-ts-template.png)
 
 ### Try it yourself
 

diff --git a/_WIP_Development/_Modern CSS/Sass.md → ...en/docs/languages-and-frameworks/sass.mdx b/_WIP_Development/_Modern CSS/Sass.md → ...en/docs/languages-and-frameworks/sass.mdx
diff --git a/...ides/development/modern-css/stylelint.mdx → ...cs/languages-and-frameworks/stylelint.mdx b/...ides/development/modern-css/stylelint.mdx → ...cs/languages-and-frameworks/stylelint.mdx
diff --git a/...s/development/modern-css/tailwind-css.mdx → ...languages-and-frameworks/tailwind-css.mdx b/...s/development/modern-css/tailwind-css.mdx → ...languages-and-frameworks/tailwind-css.mdx
diff --git a/...elopment/modern-javascript/typescript.mdx → ...s/languages-and-frameworks/typescript.mdx b/...elopment/modern-javascript/typescript.mdx → ...s/languages-and-frameworks/typescript.mdx
@@ -10,7 +10,7 @@ TypeScript is JavaScript with syntax for types.
 
 `Extension` comes with a default TypeScript template for new projects, which you can use as a starting point for your next TypeScript-based Extension. This is the easiest way to have TypeScript integrated with `Extension`.
 
-![TypeScript Extension Template](../../../../../../assets/guides/development/ts-template.png)
+![TypeScript Extension Template](../../../../../assets/guides/development/ts-template.png)
 
 #### Try it yourself
 
@@ -91,7 +91,7 @@ compilerOptions: {
 
 In order to handle the multiple import capabilities such as `import()` of JavaScript modules and file assets, `Extension` injects a `extension.d.ts` file at the root of your project folder.
 
-![TypeScript Extension Type Definition](../../../../../../assets/guides/development/extension-type-definition.png)
+![TypeScript Extension Type Definition](../../../../../assets/guides/development/extension-type-definition.png)
 
 > [!tip]
 > Ensure the `extension.d.ts` file is added to your `.gitignore` file as it is auto-generated and only useful during `development` mode.

diff --git a/...n/docs/guides/development/webassembly.mdx → .../languages-and-frameworks/webassembly.mdx b/...n/docs/guides/development/webassembly.mdx → .../languages-and-frameworks/webassembly.mdx
@@ -18,6 +18,6 @@ With WebAssembly, developers can write parts of the extension in languages like
   }}
 />
 
-![WASM Sample Extension](../../../../../assets/guides/development/wasm.png)
+![WASM Sample Extension](../../../../assets/guides/development/wasm.png)
 
 - Learn how `Extension` works with extensions using [Modern JavaScript](../development/modern-javascript/overview).