https://github.com/bnema/ublock-webkit-filters
Convert uBlock Origin filter lists to Safari/WebKitGTK content blocker JSON format
https://github.com/bnema/ublock-webkit-filters
adblock content-blocker filter-lists safari ublock-origin webkit webkitgtk
Last synced: about 16 hours ago
JSON representation
Convert uBlock Origin filter lists to Safari/WebKitGTK content blocker JSON format
- Host: GitHub
- URL: https://github.com/bnema/ublock-webkit-filters
- Owner: bnema
- License: gpl-3.0
- Created: 2025-12-19T05:11:25.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2026-05-30T05:21:45.000Z (5 days ago)
- Last Synced: 2026-05-30T07:19:18.920Z (5 days ago)
- Topics: adblock, content-blocker, filter-lists, safari, ublock-origin, webkit, webkitgtk
- Language: Go
- Size: 76.2 KB
- Stars: 3
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ublock-webkit-filters
Convert [uBlock Origin](https://github.com/gorhill/uBlock) filter lists to Safari/WebKitGTK content blocker JSON format.
## Overview
This tool fetches popular ad-blocking filter lists and converts them to the JSON format used by:
- Safari Content Blockers
- WebKitGTK `UserContentFilterStore`
Filters are updated daily via GitHub Actions and published as release artifacts.
## Download
Get the latest converted filters from [Releases](https://github.com/bnema/ublock-webkit-filters/releases/latest).
### Direct URLs (always latest)
```bash
# Combined filters (all lists merged)
https://github.com/bnema/ublock-webkit-filters/releases/latest/download/combined-part1.json
https://github.com/bnema/ublock-webkit-filters/releases/latest/download/combined-part2.json
https://github.com/bnema/ublock-webkit-filters/releases/latest/download/combined-part3.json
# Manifest with metadata
https://github.com/bnema/ublock-webkit-filters/releases/latest/download/manifest.json
```
### Files
| File | Description |
|------|-------------|
| `combined-part1.json`, `combined-part2.json`, ... | All lists merged and deduplicated (split at 150k rules) |
| `easylist.json` | EasyList - ad blocking |
| `easyprivacy.json` | EasyPrivacy - tracker blocking |
| `ublock-filters.json` | uBlock Origin optimizations |
| `manifest.json` | Metadata with rule counts |
| `checksums.txt` | SHA256 checksums |
## Usage with WebKitGTK
```go
import "github.com/user/puregotk-webkit/webkit"
// Create filter store
store := webkit.NewUserContentFilterStore("/path/to/filters")
// Load JSON filter
store.Save("combined", jsonData, nil, func(filter *webkit.UserContentFilter, err error) {
if err != nil {
log.Fatal(err)
}
// Add to content manager
contentManager.AddFilter(filter)
})
```
## Building
```bash
go build -o ublock-webkit-filters ./cmd/ublock-webkit-filters
```
## Commands
### Convert filters
```bash
# Convert all enabled lists
./ublock-webkit-filters convert --output ./output
# Dry run (parse and convert without writing files)
./ublock-webkit-filters convert --dry-run
# Verbose output
./ublock-webkit-filters convert --output ./output --verbose
```
### List configured filters
```bash
./ublock-webkit-filters list
```
### Create default config
```bash
./ublock-webkit-filters init
```
## Configuration
Edit `configs/filter_lists.toml`:
```toml
[http]
timeout = "30s"
retries = 3
[output]
max_rules_per_file = 150000
generate_combined = true
generate_manifest = true
[[lists]]
name = "easylist"
url = "https://easylist.to/easylist/easylist.txt"
enabled = true
[[lists]]
name = "easyprivacy"
url = "https://easylist.to/easylist/easyprivacy.txt"
enabled = true
# Add more lists...
```
## Filter Conversion
This project prefers safety over over-blocking: if a uBO filter cannot be represented faithfully in WebKit content blocker syntax, it is skipped rather than broadened into a more permissive rule.
### Supported
| uBlock Syntax | WebKit Action |
|---------------|---------------|
| `\|\|ads.com^` | `block` |
| `@@\|\|safe.com` | `ignore-previous-rules` |
| `##.ad-banner` | `css-display-none` |
| `$third-party` | `load-type: third-party` |
| `$script,image` | `resource-type` |
| from=example.com|foo.net | `if-domain` when representable |
### Not Supported (skipped)
- Scriptlet injection: `##+js(...)`
- HTML filtering: `##^`
- Procedural cosmetic: `:has()`, `:has-text()`, `:xpath()`
- Redirects, CSP, removeparam
- `denyallow=` resource-domain exceptions
- Mixed include/exclude domain constraints that require intersection semantics not available in WebKit
- uBO entity-matching domains such as `pingit.*`
- Regex domain values such as `domain=/.../` or `from=/.../`
- `beacon` and plugin `object` resource types when conversion would broaden them beyond the source semantics
## Default Filter Lists
- [EasyList](https://easylist.to/) - Ad blocking
- [EasyPrivacy](https://easylist.to/) - Tracker blocking
- [uBlock Origin filters](https://github.com/uBlockOrigin/uAssets) - Optimizations
- [Peter Lowe's Ad server list](https://pgl.yoyo.org/adservers/) - Adblock Plus format
## License
GPL-3.0