adguardteam / knowledgebase

AdGuard knowledge base

Website

This website is built using Docusaurus 2, a modern static website generator.

master branch is published automatically to https://adguardteam.github.io/KnowledgeBase/.

How to contribute

You can help by contributing to the Knowledge Base, all details are described in this article.

How to develop

Prepare

First of all, you need to install the following:

• git
• yarn

Second, clone this repo to your local computer:

• git clone [email protected]:AdguardTeam/KnowledgeBase.git

Alternatively, you can use the Github app to do that.

Then you should open Terminal on your computer, navigate to the directory where you cloned this repo and run this command to install the local dependencies:

• yarn install

Lint markdown

This command lints the markdown and outputs any errors to the console:

• yarn lint:md

Some of errors can be fixed automatically:

• yarn lint:md --fix

VSCode users can install the markdownlint extension to see the errors in the editor.

Run it locally

• yarn start

This command lints markdown syntax, and if there is no markdownlint errors starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.

How to build

• yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

How to translate

Localizations are not pushed to the repo and prepared on-the-fly (i18n folder is added to .gitignore).

Here's how you can debug translations locally.

1. Download translations: CROWDIN_PERSONAL_TOKEN="YOURTOKEN" yarn run crowdin download
2. Run Docusaurus with the language of your choice: yarn run start -- --locale de

knowledgebase's Issues

Add description about microShield userscript

The microShield userscript blocks Ad-Shield advertisement and anti-adblock.
Its source code is hosted at https://github.com/List-KR/microShield.
Its original source code are available at seia-soto/userscripts@master/asdefuser and seia-soto/adshield-defuser.

The following URLs are the striking resources hosted by Ad-Shield Inc.

• https://www.ad-shield.io/blog/how-ad-shield-defeated-ad-blockers-while-others-failed (Archive)
• https://www.ad-shield.io/blog/introducing-ad-shield-recovery-the-most-advanced-adblock-recovery-solution (Archive)

There are old their resources that cannot be accessed directly or are deleted. (Written in Korean language)

• https://web.archive.org/web/20220706190926/https://www.ad-shield.team/blog/how-adshield-fight
• https://web.archive.org/web/20220707020754/https://docs.ad-shield.io/update-notes
• https://web.archive.org/web/20220726130656/https://www.ad-shield.team/

For searching websites protected by Ad-Shield recovery, please click here or refer here.
For searching websites that uses Ad-Shield analytics to measure adblocking ratio, please click here and find Prevent Ad-Shield tracking script string.

The resources in some (or many) of the websites protected by Ad-Shield recovery are encoded and decoded when Ad-Shield runtime runs in your web browser.
And, on all websites that use Ad-Shield analytics or recovery, all CSS link elements in each website will be removed and the script ¹ lies that it is caused by incorrect adblock rules regardless of what it is real, if some conditions are met. ²

The following URLs are resources that are created by @seia-soto and related to Ad-Shield:

• https://www.youtube.com/live/Vw1eIaRuy7w?t=9501 (Ad-Filtering Dev Summit 2023)
• https://typed.sh/adshieldyi-modeleun-jisogganeunghaji-anheumyeo-yeoreobunyi-gaeinjeongboreul-wihyeobjeogeuro-galcwiharyeo-habnida/ (Korean language)

There is an installation guide written in Korean language at here.

Footnotes

1. The inline script starts with eval(decodeURIComponent(escape(window.atob("KCgpPT5 and a JavaScript request that starts with /loader.min.js and hosts in Ad-Shield domains such as content-loader.com, html-load.com, css-load.com and 07c225f3.online. ↩

2. Example: https://github.com/AdguardTeam/AdguardFilters/issues/167060 ↩

Userscript on Android?

I don't understand userscript on Android how can I test? I did hello world from userscript and how can I see if it works with debug output?

Thanks for reply.

Add an article about unsupported browsers

Unsupported browsers list:
https://kb.adguard.com/en/android/faq#browsers

The old article is outdated, we need assistance from the android team to compile the full list.

This article is linked from the Android app, we need to figure out for which browsers we do that.

Change the way features overview is structured in the Knowledge base

Currently, we have a single HUGE article with the overview of ALL app features.

Example:
https://adguard.com/kb/adguard-for-android/overview/

Instead of that we should create may short articles that explain each feature separately.

For example, AdGuard for Android's Features overview should be split to several articles with the following structure:

• Features
  • Protection
    • Ad blocking
    • Tracking protection
    • Annoyance blocking
    • Firewall
      • Quick actions
    • Browsing Security
  • Statistics
  • App management
  • Settings
  • Assistant
  • Free vs full version
  • Rooted vs non-rooted devices
  • Integration with AdGuard VPN

Tasks list

• Android
• macOS
• Windows
• iOS
• Browser extension
• Safari
• Content blocker

Add Ukrainian language-specific filter to KB AdGuard filters

Ukrainian language-specific filter missed:
https://adguard.com/kb/general/ad-filtering/adguard-filters/#adguard-filters

GitHub link:
https://github.com/AdguardTeam/FiltersRegistry/tree/master/filters/filter_23_Ukrainian

Add JSON examples for `$jsonprune` exapmle rules

https://github.com/AdguardTeam/KnowledgeBase
there are no json samples for provided rules.

Add an article about incompatibility of AdGuard for Mac with screen time

Problem description:

1. Open AdGuard (default settings)
2. Go to system settings - Screen Time - Content&Privacy - Content Restrictions - Access to Web Content - Limit Adult Websites - 3) Customize then add example.org to Restricted sites
3. Open Safari

As a result, the connection fails and the pages do not load.

Solution

The only solution is to disable Content&Privacy in Screen Time and reboot the system AdguardTeam/CoreLibs#1790 (comment).

Missed info in Advanced settings of AdGuard for Android app

https://adguard.com/kb/adguard-for-mac/solving-problems/advanced-settings/
Low-level settings is a subsection of Advanced settings (wrong article name)
No info about the rest of settings

Details

Update Base filter URL

https://kb.adguard.com/en/general/adguard-ad-filters

From https://raw.githubusercontent.com/AdguardTeam/FiltersRegistry/master/filters/filter_2_English/filter.txt to https://raw.githubusercontent.com/AdguardTeam/FiltersRegistry/master/filters/filter_2_Base/filter.txt

Add an article about known compatibility issues with different Android apps

Here's the old content:
https://kb.adguard.com/en/android/faq#conflicts

The old article is outdated, we need assistance from the android team to compile the full list.

This article is linked from the Android app, we need to figure out for which apps we notify the user and lead to that article.

Mandatory note about difference of the url-based and CSS-based rules

I'm rarely composing my own rules and therefore tend to forget the right syntax/modifiers/whatever comes in the rule set. The 'create-own-filters' wiki page does not explicitly specify the difference between sets of rules mentioned in the topic, while most URL modifiers are invalid for CSS rules and may confuse beginner such as myself. I'd like to propose adding a note at the beginning of the CSS rules section stating that '||', '*' and other modifiers which URL blocker uses are incompatible with CSS rule syntax to avoid possible confusion such as creating CSS rule like '||domain.com##div...'.

Instructions for MS Edge

Check the PR here:
AdguardTeam/AdguardKnowledgeBase#1143

Do we need to incorporate in in the new KB?

Update ExtendedCss section due to v2

https://github.com/AdguardTeam/ExtendedCss/blob/master/README.md

add markdownlint to AdGuard Knowledge base

let's add markdownlint like it was done in AdGuard VPN KB: AdguardTeam/KnowledgeBaseVPN#119

Update filters policy

The last changes in old KB were reverted.
Restore these changes (30k => 100 thousand visits per month)
AdguardTeam/AdguardKnowledgeBase@7e69797

Add an article about moving the certificate to system storage

HTTPS filtering of non-browser apps on Android requires moving the certificate to System store.
This option is only available on rooted devices. We should add an article that explains how to do that and what limitations there are.

Review the "background work" article

Here's the article that needs to be reviewed:
https://adguard.com/kb/adguard-for-android/solving-problems/background-work/

Review the content and make sure that its content is up-to-date, see https://dontkillmyapp.com/ for more information.

Blocking links from Firefox Pocket

After the most recent update AdGuard is blocking opening new tabs and new windows from the right click menu and straight click-through links from Pocket, but only for NSFW sites. Even other normally heavily ad-laden sites are able to be opened from Pocket, only NSFW sites appear to be blocked.

Add "Do not track me Google" to recommended userscripts

We have an article about userscripts: https://adguard.com/kb/general/userscripts/

We should split "Recommended AdGuard userscripts" into two sections:

• AdGuard userscripts -- those that are actually made by us
• Top picks -- those, that we can recommend. microShield goes to that section for instance.

Here's the userscript:
https://greasyfork.org/en/scripts/428243-don-t-track-me-google

The homepage:
https://github.com/Rob--W/dont-track-me-google

Add a separate chapter for DNS-related modifiers to the "Your own filters" article

The chapter should have information about which AdGuard apps support which modifiers and contain a link leading to the DNS KB article about those modifiers' syntax

Awarding the best AdGuard contributors in 2023

Hello, @superlex!

My name is Anna, I'm a content manager at AdGuard. We get in touch with contributors so we can send gifts to those who help a lot. Could you contact me to discuss the details? My email is [email protected].

Improve Safari Web extension article

1. go to Settings → Safari → Extensions
2. select "Ask" for AdGuard extension
3. go to any website
4. Aa → AdGuard, and allow just for this particular website (not for every website)
5. do Aa → AdGuard again

as a result there will be Limited permissions shown in AdGuard Safari web extension popup:
https://uploads.adguard.org/slbdzdrvjk3ae.png

but this phrase—"Limited permissions"—is not mentioned in the KB article and there is no screenshot with such popup state. so the article may be improved because now it's not clear for a user is it a problem and how to deal with it

Fix formatting of the "compatibility issues" page content

That's now how numbered lists are to be formatted.

Also, stick to using headers instead so that they get to the page table of contents sidebar.

The AdGuard kb doesn’t follow the system theme

The AdGuard kb doesn’t follow the system theme in Safari for macOS. Please consider implementing this.

macOS: 13.2 (22D49)
Safari: 16.3 (18614.4.6.1.5)

Reported by @jslawler

Adware and Viruses article is outdated

The article is outdated.

Here's the list of issues with it:

1. Kaspersky tool links to a Ru website
2. There are more free scanning tools, why don't we recommend them?
3. "Free antivirus utilities" should be a header so that it was in the TOC
4. "How to remove ...." sections are outdated, these types of adware are not used anymore so this all can be safely removed

Describe when native CSS4 ':has()' can be used and how it is handled in browsers without native ':has()' support

• Add examples for CSS4 ':has()';
• Describe limitations of CSS4 ':has()' or add the link https://www.w3.org/TR/selectors-4/#relational and which rules can be converted to native;
• Describe how CSS4 ':has()' handled in browsers without it's support (old Safari, Firefox without experimental flags), including cases where the selector is not supported by CSS4 (:has(:contains(aaa)));
• in which cases native implementation may fail to hide an element;
• performance comparison.

Remove "Technical support" page from KB

Talking about this:
https://adguard.com/kb/support/contact/

It duplicates the page that we already have:
https://adguard.com/en/support.html

Add more tools in `$jsonprune` section

Remove

• https://jsonpath.herokuapp.com/ is not working anymore

  Details

  

Add as clickable links

• https://www.site24x7.com/tools/jsonpath-finder-validator.html

  Allows to copy a path, conveniently to explore the json

  Details

  

• https://jsonpathfinder.com/

  As previous.

Yarn build errors

When attempting to build with yarn build, I received the below errors.
It looks like it's trying to build with a version of nodejieba that doesn't exist. The latest version is 2.5.2, not 2.6.0.

Looking into the issue tracker, it appears to have been pulled at the moment due to issues, with the recommendation to use 2.5.2.

[redacted]@[redacted]s-MacBook-Pro KnowledgeBase % yarn install
yarn install v1.22.19
[1/4] 🔍  Resolving packages...
[2/4] 🚚  Fetching packages...
[3/4] 🔗  Linking dependencies...
warning " > [email protected]" has unmet peer dependency "webpack@^4.0.0 || ^5.0.0".
warning "@docusaurus/core > [email protected]" has unmet peer dependency "react-loadable@*".
warning " > [email protected]" has unmet peer dependency "webpack@^4.0.0 || ^5.0.0".
warning "@docusaurus/core > react-dev-utils > [email protected]" has unmet peer dependency "typescript@>= 2.7".
warning "@docusaurus/plugin-ideal-image > @endiliey/[email protected]" has unmet peer dependency "prop-types@>=15".
warning "@docusaurus/preset-classic > @docusaurus/theme-search-algolia > @docsearch/[email protected]" has unmet peer dependency "@types/react@>= 16.8.0 < 19.0.0".
warning "docusaurus-theme-search-typesense > [email protected]" has unmet peer dependency "algoliasearch@>= 3.1 < 6".
warning "docusaurus-theme-search-typesense > typesense-docsearch-react > @algolia/[email protected]" has unmet peer dependency "@algolia/client-search@^4.9.1".
warning "docusaurus-theme-search-typesense > typesense-docsearch-react > @algolia/[email protected]" has unmet peer dependency "algoliasearch@^4.9.1".
warning " > [email protected]" has unmet peer dependency "@docusaurus/[email protected]".
warning "docusaurus-theme-search-typesense > [email protected]" has unmet peer dependency "@types/react@>= 16.8.0 < 19.0.0".
warning "docusaurus-theme-search-typesense > [email protected]" has unmet peer dependency "@babel/runtime@^7.17.2".
warning "docusaurus-theme-search-typesense > typesense-docsearch-react > [email protected]" has unmet peer dependency "@babel/runtime@^7.17.2".
[4/4] 🔨  Building fresh packages...
[-/5] ⠁ waiting...
[-/5] ⠁ waiting...
[3/5] ⠁ sharp
[-/5] ⠁ waiting...
error /Users/[redacted]/Documents/GitHub/KnowledgeBase/node_modules/nodejieba: Command failed.
Exit code: 1
Command: node-pre-gyp install --fallback-to-build
Arguments: 
Directory: /Users/[redacted]/Documents/GitHub/KnowledgeBase/node_modules/nodejieba
Output:
node-pre-gyp info it worked if it ends with ok
node-pre-gyp info using [email protected]
node-pre-gyp info using [email protected] | darwin | x64
node-pre-gyp info check checked for "/Users/[redacted]/Documents/GitHub/KnowledgeBase/node_modules/nodejieba/build/Release/nodejieba.node" (not found)
node-pre-gyp http GET https://github.com/yanyiwu/nodejieba/releases/download/v2.6.0/nodejieba-v2.6.0-node-v115-darwin-x64.tar.gz
node-pre-gyp ERR! install response status 404 Not Found on https://github.com/yanyiwu/nodejieba/releases/download/v2.6.0/nodejieba-v2.6.0-node-v115-darwin-x64.tar.gz 
node-pre-gyp WARN Pre-built binaries not installable for [email protected] and [email protected] (node-v115 ABI, unknown) (falling back to source compile with node-gyp) 
node-pre-gyp WARN Hit error response status 404 Not Found on https://github.com/yanyiwu/nodejieba/releases/download/v2.6.0/nodejieba-v2.6.0-node-v115-darwin-x64.tar.gz 
node-pre-gyp ERR! build error 
node-pre-gyp ERR! stack Error: Failed to execute 'node-gyp clean' (Error: spawn node-gyp ENOENT)
node-pre-gyp ERR! stack     at ChildProcess.<anonymous> (/Users/[redacted]/Documents/GitHub/KnowledgeBase/node_modules/@mapbox/node-pre-gyp/lib/util/compile.js:83:23)
node-pre-gyp ERR! stack     at ChildProcess.emit (node:events:512:28)
node-pre-gyp ERR! stack     at ChildProcess._handle.onexit (node:internal/child_process:291:12)
node-pre-gyp ERR! stack     at onErrorNT (node:internal/child_process:483:16)
node-pre-gyp ERR! stack     at process.processTicksAndRejections (node:internal/process/task_queues:82:21)
node-pre-gyp ERR! System Darwin 22.5.0
node-pre-gyp ERR! command "/usr/local/Cellar/node/20.4.0/bin/node" "/Users/[redacted]/Documents/GitHub/KnowledgeBase/node_modules/nodejieba/node_modules/.bin/node-pre-gyp" "install" "--fallback-to-build"
node-pre-gyp ERR! cwd /Users/[redacted]/Documents/GitHub/KnowledgeBase/node_modules/nodejieba
node-pre-gyp ERR! node -v v20.4.0

Update compatibility of 'websocket' modifier

Description:
https://adguard.com/kb/general/ad-filtering/create-own-filters/#websocket-modifier

Related issue:
AdguardTeam/AdGuardForSafari#699 (comment)

'websocket' modifier is supported starting Macos 12 / iOS 16

The links at the "Debugging scriptlets" section are dead

The scriptlet links at the Debugging scriptlets section lead to the document all returning "404 - page not found".

Add info about installing proxy certificate on Windows and Mac

there are only for Android and iOS now, would be nice to have instructions for Windows and Mac as well
https://adguardteam.github.io/KnowledgeBase/guides/proxy-certificate

Add a Family Link certificate installation manual

User 737849 (CRM ID) suggests that we add this working manual to the public knowledge base

Make new screenshots for the AG for Mac Overview article

The article in Russian (https://adguard.com/kb/ru/adguard-for-mac/overview/) currently displays screenshots in English. We should add screenshots in Russian.

The screenshot under "Network" should also have the "Automatically filter applications" checkbox ticked, we need to upload a new one. This applies to the EN article too.

Add an article about Proxy certificate installation

This article is missing from the new KB:
https://kb.adguard.com/en/technical-support/how-to-install-certificate

I suggest placing it under General->HTTPS filtering.

Android section should mention that the apps do not trust user certs by default.

Browser protected pages

          Browser protected pages:

https://github.com/gorhill/uBlock/wiki/Privileged-Pages

I suggest write similar note in AdGuard KB.

Or steal idea from Stylus (promtped at top in pop-up "dashboard"):

Firefox forbids access to the site.

To allow access open about:config, right-click the list, click 'New', then 'Boolean', paste privacy.resistFingerprinting.block_mozAddonManager and click OK, true, OK, reload the addons.mozilla.org page.

• (Чтобы разрешить доступ, перейдите на адрес about:config, нажмите правой кнопкой в списке, потом «Создать», потом «Логическое», вставьте текст privacy.resistFingerprinting.block_mozAddonManager и нажмите OK, , OK, перезагрузите страницу addons.mozilla.org.)

In Firefox 60 and newer you need to remove this domain from extensions.webextensions.restrictedDomains in about:config.

• (В Firefox 60 и новее вам нужно удалить этот домен из extensions.webextensions.restrictedDomains в about:config.)

Costs with use Stylus idea is broken button "remove extension" on webage addon description.

Originally posted by @krystian3w in #198 (comment)

Add description for `$inline-script` and `$inline-font`

check if they work similarly in corelibs and tsurlfilter

Add an article about Samsung Pay app in Korea

The original content is here:
How to use Samsung Pay with AdGuard in South Korea

Currently, this article is missing from the new KB.

Add article about known issues of AdGuard for Windows to KB

In this article we can write about issues such as AdguardTeam/AdguardForWindows#3884

Fix wording in the "Writing about AdGuard" article

This part:

If you want to make a video or to do something else, let us know in advance, just to avoid misunderstandings in the future. The same applies if your plan includes the use of AdGuard logo, banners or other visual elements. The contact email remains the same: [email protected].

https://adguard.com/kb/miscellaneous/contribute/writing-about-adguard/

Use admonitions instead of quotes in the documentation

There are quite a lot of places in the knowledge base where we use quotes where we should actually use admonitions.

Just search for all lines that start with > , they all should be reworked as admonitions.

I.e. instead of this:
https://uploads.adguard.org/up04_How_to_create_your_own_ad_filters__AdGuard_Knowledge_Base_dk2q0.png

We should have this:
https://uploads.adguard.org/up04_How_to_create_your_own_ad_filters__AdGuard_Knowledge_Base_z8h3u.png

Empty code block in Safari HAR export instructions

@el-termikael, was the empty code block in the Safari HAR export instructions intentional?

Update examples for $permissions modifier

there are no sync-xhr, oversized-images, etc among the Permissions-Policy available directives

https://uploads.adguard.org/slbdzdrvt248a.png

https://adguard.com/kb/general/ad-filtering/create-own-filters/#permissions-modifier

Apps to sleep

Hi!
Please clarify if following the Samsung guide at https://github.com/AdguardTeam/AdguardKnowledgeBase/blob/master/04.android/06.solving-problems/09.background-work/docs.en.md will disable the relevant options only for AdGuard and all the other apps may go to sleep. I would like to put other apps to sleep.

Browser protected pages

@adguard-bot commented on Fri May 19 2023

Issue URL (Social Widget)

https://addons.mozilla.org/blog/translate-the-web-easily-with-a-browser-extension/

Comment

Username: @Spok1

Screenshots

Screenshot 1

System configuration

Information	value
AdGuard product:	AdGuard Browser extension v4.1.55
Browser:	Firefox
Stealth mode options:	Hide your search queries, Send Do-Not-Track header, Strip URLs from tracking parameters, Hide your Referrer from third-parties
Filters:	Ad Blocking: AdGuard Base, AdGuard Mobile Ads Privacy: AdGuard URL Tracking, AdGuard Tracking Protection Social Widgets: AdGuard Social Media Annoyances: AdGuard Annoyances Language-specific: AdGuard Russian, AdGuard Ukrainian

Kb search often takes an excessive amount of time to show up

Sometimes it loads instantly when tapped, other times it takes up to ~10 seconds before it shows.

Showing search should really be a close to instantaneous action, consistently in this age of the internet.

Upload.from.GitHub.for.iOS.MOV

Describe all supported aliases

For instance, the $first-party is an alias of $~third-party, etc.