-
Notifications
You must be signed in to change notification settings - Fork 187
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'master' into fix/advanced-blocking-safari-desc-001
- Loading branch information
Showing
95 changed files
with
198 additions
and
7,161 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,9 +1,10 @@ | ||
| --- | ||
| title: Userscripts | ||
| sidebar_position: 5 | ||
| toc_max_heading_level: 4 | ||
| title: Extensions | ||
| sidebar_position: 6 | ||
| --- | ||
|
|
||
| ## Userscripts | ||
|
|
||
| Userscripts (we also call them "extensions") are, de facto, miniprograms written in JavaScript. They modify or extend the functionality of one or more websites. Many AdGuard users may be already familiar with such userscripts as AdGuard Assistant, Popup Blocker, and AdGuard Extra. | ||
|
|
||
| :::note Supported apps | ||
|
|
@@ -12,83 +13,83 @@ AdGuard can significantly broaden website functionality by acting as a userscrip | |
|
|
||
| ::: | ||
|
|
||
| ## Recommended AdGuard scripts | ||
| ### Recommended AdGuard scripts | ||
|
|
||
| These userscripts come directly from the AdGuard developers, and we can guarantee that they are effective and safe. For some of the userscripts developed by others that we consider good and reliable, [scroll down to the next section](#top-picks). You can also find some of the [popular websites with scripts](#more-userscripts) below, but remember that whenever you download a userscript from an unknown source, you expose yourself to a certain risk, as some scripts may be harmful to your computer. | ||
| These userscripts come directly from the AdGuard developers, and we can guarantee that they are effective and safe. For some of the userscripts developed by others that we consider good and reliable, [scroll down to the next section](#top-picks). You can also find some of the [popular websites with scripts](#more-userscripts) below, but remember that whenever you download a userscript from an unknown source, you are exposing yourself to a certain risk, as some scripts may be harmful to your computer. | ||
|
|
||
| ### AdGuard Extra | ||
| #### AdGuard Extra | ||
|
|
||
| An extension that blocks ads in difficult cases when the usual filter-based approach is not enough. AdGuard Extra comes pre-installed with all premium AdGuard versions, so you don't need to do anything to enable it. However, if you want to use it alongside AdGuard Browser Extension or any other ad blocker, you'll need to use an additional extension. Learn more about this userscript and how to install it on [GitHub](https://github.com/AdguardTeam/AdGuardExtra). | ||
| An extension that blocks ads in difficult cases when the usual filter-based approach is not enough. AdGuard Extra comes pre-installed in AdGuard standalone apps, except for the one for iOS, so you don't need to do anything to enable it. However, if you want to use it alongside AdGuard Browser Extension or any other ad blocker, you'll need to use an additional extension. Learn more about this userscript and how to install it on [GitHub](https://github.com/AdguardTeam/AdGuardExtra). | ||
|
|
||
|  | ||
|
|
||
| ### AdGuard Popup Blocker | ||
| #### AdGuard Popup Blocker | ||
|
|
||
| The name speaks for itself: it blocks pop-ups — one of the most annoying types of ads on web pages. Learn more about this userscript, its key features, and how to install it on [GitHub](https://github.com/AdguardTeam/PopupBlocker). | ||
| The name speaks for itself: it blocks popups — one of the most annoying types of ads on websites. Learn more about this userscript, its key features, and installation on [GitHub](https://github.com/AdguardTeam/PopupBlocker). | ||
|
|
||
|  | ||
|
|
||
| ### AdGuard Assistant (legacy version) | ||
| #### AdGuard Assistant (legacy version) | ||
|
|
||
| This custom extension is designed to control filtering directly from the browser page (manual blocking, exclusion of the site, etc.). | ||
| This custom extension is designed to control filtering directly from the browser page (manual blocking, allowlisting, etc.). | ||
|
|
||
| :::note | ||
|
|
||
| This version of Assistant is legacy and there is no point in using it on new systems, since it has been replaced with the full-fledged [Browser Assistant](https://adguard.com/adguard-assistant/overview.html). But the legacy Assistant might be of help if there is no Browser Assistant for your browser. If this is your case, your can learn how to install AdGuard Assistant on [GitHub](https://github.com/AdguardTeam/AdguardAssistant). | ||
| This version of Assistant is legacy and there is no point in using it on new systems, as it has been replaced with the full-fledged [Browser Assistant](https://adguard.com/adguard-assistant/overview.html). However, the legacy Assistant may be useful if there is no Browser Assistant for your browser. If this is your case, you can learn how to install AdGuard Assistant on [GitHub](https://github.com/AdguardTeam/AdguardAssistant). | ||
|
|
||
| ::: | ||
|
|
||
| ### Disable AMP | ||
| #### Disable AMP | ||
|
|
||
| A script that is only pre-installed in AdGuard for Android. It disables AMP (Accelerated Mobile Pages) on the Google search results page. Learn more about this userscript and how to install it on [GitHub](https://github.com/AdguardTeam/DisableAMP). | ||
|
|
||
|  | ||
|
|
||
| ## Top picks outside AdGuard{#top-picks} | ||
| ### Top picks outside AdGuard{#top-picks} | ||
|
|
||
| These userscripts are not developed by AdGuard and therefore we can't give a 100% guarantee that they are safe and/or work at all times. However, in our experience they deserve a recommendation as they've all earned their good reputation. | ||
| These userscripts are not developed by AdGuard, and therefore we can't give a 100% guarantee that they are safe and/or work at all times. However, in our experience they deserve a recommendation because they've all earned their good reputation. | ||
|
|
||
| ### Don't track me Google | ||
| #### Don't track me Google | ||
|
|
||
| This script removes Google's tracking feature from the links in Google search results. It speeds up the loading of search results and allows you to right-click or tap to copy the link URL. | ||
|
|
||
| Its source code is [available on GitHub](https://github.com/Rob--W/dont-track-me-google). This userscript can be downloaded from [GreasyFork](https://greasyfork.org/en/scripts/428243-don-t-track-me-google) and installed in any AdGuard CoreLibs-based app. | ||
|
|
||
| ### microShield | ||
| #### microShield | ||
|
|
||
| A userscript for people who visit Korean websites and some international websites. The microShield userscript blocks Ad-Shield advertisement and anti-adblock. Its original source code is available at [asdefuser](https://github.com/seia-soto/userscripts/tree/master/sources/asdefuser) and [AdShield Defuser](https://github.com/seia-soto/adshield-defuser). This userscript can be installed in AdGuard CoreLibs-based apps, Violentmonkey, Tampermonkey, and [quoid/userscripts](https://github.com/quoid/userscripts). Learn more about microShield and how to install it on [GitHub](https://github.com/List-KR/microShield). | ||
| A userscript for people visiting Korean websites and some international websites. The microShield userscript blocks Ad-Shield ads and anti-adblocks. Its original source code is available at [asdefuser](https://github.com/seia-soto/userscripts/tree/master/sources/asdefuser) and [AdShield Defuser](https://github.com/seia-soto/adshield-defuser). This userscript can be installed in AdGuard CoreLibs-based apps, Violentmonkey, Tampermonkey, and [quoid/userscripts](https://github.com/quoid/userscripts). Learn more about microShield and how to install it on [GitHub](https://github.com/List-KR/microShield). | ||
|
|
||
| ## Where can you get more userscripts?{#more-userscripts} | ||
| ### Where can you get more userscripts?{#more-userscripts} | ||
|
|
||
| As userscripts are mainly created by enthusiasts, you should be cautious when installing them. Any script from an unknown source carries a potential risk. Yet, there is a great variety of interesting scripts that, if installed carefully and responsibly, can really make using some websites more convenient. | ||
| Since userscripts are mainly created by enthusiasts, you should be cautious when installing them. Any script from an unknown source carries a potential risk. Yet, there is a great variety of interesting scripts that, if installed carefully and responsibly, can really make using some websites more convenient. | ||
|
|
||
| Here we will describe some of the most popular userscript catalogs. | ||
|
|
||
| ### Userscript.Zone | ||
| #### Userscript.Zone | ||
|
|
||
| [Userscript.Zone](https://www.userscript.zone) is a website that allows searching for userscripts by entering a matching URL or domain. The website is easy to use and has a high credibility, since only scripts from moderated pages are displayed. | ||
| [Userscript.Zone](https://www.userscript.zone) is a website that allows searching for userscripts by entering a matching URL or domain. The website is easy to use and has a high level of credibility as only scripts from moderated pages are displayed. | ||
|
|
||
| ### Greasy Fork | ||
| #### Greasy Fork | ||
|
|
||
| [Greasy Fork](https://greasyfork.org/) is a userscript catalog by Stylish creators. The scripts in this catalog undergo moderation, so their credibility is much higher. | ||
| [Greasy Fork](https://greasyfork.org/) is a userscript catalog of Stylish creators. The scripts in this catalog are moderated, so their credibility is much higher. | ||
|
|
||
| ### OpenUserJS.org | ||
| #### OpenUserJS.org | ||
|
|
||
| [OpenUserJS.org](https://openuserjs.org/) is an open source userscript catalog written in nodeJS. It doesn't have moderation so stay alert to any suspicious scripts. | ||
| [OpenUserJS.org](https://openuserjs.org/) is an open-source userscript catalog written in nodeJS. It's not moderated, so keep an eye out for suspicious scripts. | ||
|
|
||
| ### Community | ||
| #### Community | ||
|
|
||
| If you like the idea of personifying your browser with the help of userscripts, and you have any questions, you can ask them on one of these websites: | ||
| If you like the idea of customizing your browser with userscripts and have questions, you can ask them on one of these websites: | ||
|
|
||
| - [Stackoverflow](https://stackoverflow.com/questions/tagged/userscripts) | ||
| - [FreeNode](https://webchat.freenode.net/#greasemonkey) | ||
| - [Reddit](https://www.reddit.com/r/userscripts/) | ||
|
|
||
| ## Development | ||
| ### Development | ||
|
|
||
| ### Request license | ||
| #### Request license | ||
|
|
||
| If you are developing your own custom script and want to test how it works with AdGuard, request a beta license key for the app. | ||
| If you are developing your own custom script and want to test how it works with AdGuard, you can request a beta license key for the app. | ||
|
|
||
| To get it, please send an email to [email protected] with the following information: | ||
|
|
||
|
|
@@ -98,11 +99,11 @@ To get it, please send an email to [email protected] with the following inform | |
|
|
||
| Here is a [mailto link](mailto:[email protected]?Subject=Userscript%20author%20license%20request&Body=Hello%2C%0A%0AMy%20userscript%28s%29%3A%20LINK). | ||
|
|
||
| ### Compatibility | ||
| #### Compatibility | ||
|
|
||
| #### Metadata block | ||
|
|
||
| ##### Supported properties | ||
| #### Supported properties | ||
|
|
||
| ```text | ||
| @name | ||
|
|
@@ -132,7 +133,7 @@ Here is a [mailto link](mailto:[email protected]?Subject=Userscript%20author%2 | |
| @icon64URL | ||
| ``` | ||
|
|
||
| ##### Unsupported properties | ||
| #### Unsupported properties | ||
|
|
||
| These properties will be simply ignored by AdGuard. | ||
|
|
||
|
|
@@ -144,7 +145,7 @@ These properties will be simply ignored by AdGuard. | |
|
|
||
| AdGuard supports both old GM\_ functions and new GM4 API that use GM object. | ||
|
|
||
| ##### Values | ||
| #### Values | ||
|
|
||
| :::note | ||
|
|
||
|
|
@@ -171,7 +172,7 @@ GM_log | |
|
|
||
| [Here](https://wiki.greasespot.net/GM.info) you can find more information about Greasemonkey API. | ||
|
|
||
| ### Example | ||
| #### Example | ||
|
|
||
| ```javascript | ||
| // ==UserScript== | ||
|
|
@@ -212,22 +213,72 @@ GM_log | |
|
|
||
| ## Userstyles | ||
|
|
||
| AdGuard products provide limited support for userstyles. `@var` and `@advanced` metadata tags are not supported, | ||
| as well as any value of the `@preprocessor` metadata tag except `default`. | ||
| Userstyles allow users to customize their online experience. Whether you’re looking to change the appearance of a website or automate repetitive tasks, styles offer a world of possibilities. | ||
|
|
||
| AdGuard has the option to upload or create your own userstyles. This is an advanced feature, so you will need some knowledge of HTML and CSS. | ||
|
|
||
| :::info Supported apps | ||
|
|
||
| Currently, two AdGuard apps allow you to create and manage userstyles: AdGuard for Windows (v7.19 or later) and AdGuard for Mac (v2.16 or later). We also plan to implement this new feature in AdGuard v4.8 for Android in the nearest future. | ||
|
|
||
| ::: | ||
|
|
||
| This is an experimental feature, so if you encounter any problems while adding or creating a userstyle, please contact our support team at <[email protected]>. | ||
|
|
||
| ### How to set up a userstyle in AdGuard | ||
|
|
||
| You can download userstyles from various websites. One of the most popular userstyle websites is [https://userstyles.world/](https://userstyles.world/explore), which we will use as an example for the following instructions on how to set up the userstyle in AdGuard. | ||
|
|
||
| 1. Follow the link above and choose the userstyle you like | ||
|
|
||
| 1. Right-click the *Install* button and choose *Copy Link Address* | ||
|
|
||
| 1. Open AdGuard settings → *Extensions* | ||
|
|
||
| 1. Press the [+] button and paste the userstyle link | ||
|
|
||
| ### Metadata | ||
| 1. Done! | ||
|
|
||
| If you’re familiar with CSS rules, you can also create the userstyles yourself. | ||
|
|
||
| :::note | ||
|
|
||
| We don’t support userstyles that contain `@var` or `@advanced` in the metadata. AdGuard also doesn’t support `@preprocessor` without the `default` value. | ||
|
|
||
| ::: | ||
|
|
||
| 1. Open AdGuard settings → *Extensions* | ||
|
|
||
| 1. Press the [+] button and choose the *Create userstyle* option. A new window will appear on your screen | ||
|
|
||
| 1. To create a userstyle, first write the title with metadata, for example | ||
|
|
||
| ```CSS | ||
| /* ==UserStyle== | ||
| @name New userstyle | ||
| @version 1.0 | ||
| ==/UserStyle== */ | ||
| ``` | ||
|
|
||
| 1. Write the CSS part after the meta data. AdGuard supports website domain names matching (`@-moz-document domain(…), …`). For example: | ||
|
|
||
| ```CSS | ||
| body { | ||
| background: gray; | ||
| } | ||
| ``` | ||
|
|
||
| The metadata block is written using CSS-style comments, starting with `===UserStyle===` and ending with `===/UserStyle===`. | ||
| All metadata tags that are supported for userscripts are also supported for userstyles, although some of them have no meaning and are ignored. | ||
| `@var` and `@advanced` tags are not supported. | ||
| The only supported value of the `@preprocessor` tag is `default`. | ||
| Or: | ||
|
|
||
| ### Content | ||
| ```CSS | ||
| @-moz-document domain('example.org'), | ||
| domain('example.net'), | ||
| domain('example.com') body { | ||
| background: gray; | ||
| } | ||
| ``` | ||
|
|
||
| The content of a userstyle is plain CSS with support for the [`@-moz-document` at-rule](https://developer.mozilla.org/en-US/docs/Web/CSS/@document). | ||
| The `media-document()` function is not supported. | ||
| The userstyle will only be applied to pages that match one or more of the `@-moz-document` rules. | ||
| If the userstyle does not contain any `@-moz-document` rules, it will not be applied. | ||
| 1. Once you’re finished, press *Save and Close*. Your new userstyle has been successfully added to AdGuard | ||
|
|
||
| ### Example | ||
|
|
||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.