Explain basic syntax in the my filters docs, docsUX #3919
Description
Prerequisites
- I verified that this is not a filter list issue. Report any issues with filter lists or broken website functionality in the uAssets issue tracker.
- This is NOT a YouTube, Facebook or Twitch report. These sites MUST be reported by clicking their respective links.
- This is not a support issue or a question. For support, questions, or help, visit /r/uBlockOrigin.
- I performed a cursory search of the issue tracker to avoid opening a duplicate issue.
- The issue is not present after disabling uBO in the browser.
- I checked the documentation to understand that the issue I am reporting is not normal behavior.
I tried to reproduce the issue when...
- uBO is the only extension.
- uBO uses default lists and settings.
- using a new, unmodified browser profile.
Description
Explain basic syntax in the docs, set the expectations.
A specific URL where the issue occurs.
https://github.com/gorhill/uBlock/wiki/Dashboard:-My-filtersSteps to Reproduce
- Settings.
- My filters (
moz-extension://.../dashboard.html#1p-filters.html). - Docs icon -> https://github.com/gorhill/uBlock/wiki/Dashboard:-My-filters
Expected behavior
Explain the syntax roughly, point to more details. Explain the options later.
Perhaps explain what to expect in current article (abstract aka summary aka TL;DR).
Or link to another page that does that.
Actual behavior
Above the fold I can only see a trusted filter screen.
Even reading the rest of this page it is impossible to get the feeling of what the filters are and what they can do. So show a few examples from simple to advanced.
So perhaps something like this:
My filters
...Abstract perhaps?...
TOC
Syntax of filters
Let's start with a simple example:
http://example.com/abs.js
This will block this specific URL as written and all URLs that start with that so also http://example.com/abs.js/abc.
||example.com/abs.js
Will be protocol independent so both http:// and https:// will be blocked. The || is a modifier prefix.
You could also use @@ to make an accept-filter (by default filters are blocking). Note that accept filters are more important then blocking filters.
So the syntax is:
{`modifier prefixes`}{`url` or `regexp`]${`options` (separated by a comma)}See more about the syntax in: Static filter syntax.
The warning
...
Order of filters
Note that what you enter in "My filters" might be overriden by other filters. See the logger to check which filter was applied.
Remember that accept filters are more important then blocking filters. So to block an url that has an accept filter you will need to use the important option.
Options
[the screen that is now on top]
...the rest as-is...
Notes
- Not sure if I named the parts correctly you might want to adjust. I haven't found this.
- Not sur if there needs to be variants of this syntax. Haven't looked at AST/tokens.
uBO version
1.68.0
Browser name and version
Firefox: 149
Operating System and version
Win11pro 25H2