@adguard/agtree/README.md

Tool set for working with adblock filter lists

<!-- markdownlint-disable -->
&nbsp;
<p align="center">
    <picture>
        <source media="(prefers-color-scheme: dark)" srcset="https://cdn.adtidy.org/website/github.com/AGTree/agtree_darkmode.svg" />
        <img alt="AGTree" src="https://cdn.adtidy.org/website/github.com/AGTree/agtree_lightmode.svg" width="350px" />
    </picture>
</p>
<h3 align="center">Tool set for working with adblock filter lists</h3>
<p align="center">Supported syntaxes:</p>
<p align="center">
    <img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg" width="14px" alt="AdGuard logo" /> <a href="https://adguard.com">AdGuard</a>
    | <img src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg" width="14px" alt="uBlock Origin logo" /> <a href="https://github.com/gorhill/uBlock">uBlock Origin</a>
    | <img src="https://cdn.adguard.com/website/github.com/AGLint/ab_logo.svg" width="14px" alt="AdBlock logo" /> <a href="https://getadblock.com">AdBlock</a>
    | <img src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg" width="14px" alt="Adblock Plus logo" /> <a href="https://adblockplus.org">Adblock Plus</a>
</p>
<p align="center">
    <a href="https://www.npmjs.com/package/@adguard/agtree"><img src="https://img.shields.io/npm/v/@adguard/agtree" alt="NPM version" /></a>
    <a href="https://www.npmjs.com/package/@adguard/agtree"><img src="https://img.shields.io/npm/dm/@adguard/agtree" alt="NPM Downloads" /></a>
    <a href="https://github.com/AdguardTeam/tsurlfilter/blob/master/packages/agtree/LICENSE"><img src="https://img.shields.io/npm/l/@adguard/agtree" alt="License" /></a>
</p>
<!-- markdownlint-restore -->

## What is AGTree?

AGTree is a tool set for working with adblock filter lists. It contains the following modules:

- [Adblock rule parser][parser-url]
- [Adblock rule converter][converter-url]
- [Adblock rule validator][validator-url]
- [Compatibility tables][compatibility-tables-url]

## Installation

You can install the library using

- [Yarn][yarn-pkg-manager-url]: `yarn add @adguard/agtree`
- [NPM][npm-pkg-manager-url]: `npm install @adguard/agtree`
- [PNPM][pnpm-pkg-manager-url]: `pnpm add @adguard/agtree`

> [!IMPORTANT]
> AGTree is an ESM-only package and requires Node.js version 18 or higher.

[yarn-pkg-manager-url]: https://yarnpkg.com/en/docs/install
[npm-pkg-manager-url]: https://www.npmjs.com/get-npm
[pnpm-pkg-manager-url]: https://pnpm.io/

## Development & Contribution

Please read the [CONTRIBUTING.md][contributing-url] file for details on how to contribute to this project.

## Ideas & Questions

If you have any questions or ideas for new features, please [open an issue][new-issue-url] or a
[discussion][discussions-url]. We will be happy to discuss it with you.

## License

AGTree is licensed under the MIT License. See the [LICENSE][license-url] file for details.

## References

Here are some useful links to help you write adblock rules. This list is not exhaustive, so if you know any other useful
resources, please let us know.

<!--markdownlint-disable MD013-->
- Syntax documentation:
    - <img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg" width="14px" alt="AdGuard logo"> [AdGuard: *How to create your own ad filters*][adg-filters]
    - <img src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg" width="14px" alt="uBlock Origin logo"> [uBlock Origin: *Static filter syntax*][ubo-filters]
    - <img src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg" width="14px" alt="Adblock Plus logo"> [Adblock Plus: *How to write filters*][abp-filters]
- Extended CSS documentation:
    - [MDN: *CSS selectors*][mdn-css-selectors]
    - <img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg" width="14px" alt="AdGuard logo"> [AdGuard: *Extended CSS capabilities*][adg-ext-css]
    - <img src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg" width="14px" alt="uBlock Origin logo"> [uBlock Origin: *Procedural cosmetic filters*][ubo-procedural]
    - <img src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg" width="14px" alt="Adblock Plus logo"> [Adblock Plus: *Extended CSS selectors*][abp-ext-css]
- Scriptlets:
    - <img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg" width="14px" alt="AdGuard logo"> [AdGuard scriptlets][adg-scriptlets]
    - <img src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg" width="14px" alt="uBlock Origin logo"> [uBlock Origin scriptlets][ubo-scriptlets]
    - <img src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg" width="14px" alt="Adblock Plus logo"> [Adblock Plus snippets][abp-snippets]
- <img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg" width="14px" alt="AdGuard logo"> [AdGuard's compatibility table][adg-compatibility-table]
<!--markdownlint-enable MD013-->

[abp-ext-css]: https://help.eyeo.com/adblockplus/how-to-write-filters#elemhide-emulation
[abp-filters]: https://help.eyeo.com/adblockplus/how-to-write-filters
[abp-snippets]: https://help.eyeo.com/adblockplus/snippet-filters-tutorial#snippets-ref
[adg-compatibility-table]: https://github.com/AdguardTeam/Scriptlets/blob/master/wiki/compatibility-table.md
[adg-ext-css]: https://github.com/AdguardTeam/ExtendedCss/blob/master/README.md
[adg-filters]: https://kb.adguard.com/en/general/how-to-create-your-own-ad-filters
[adg-scriptlets]: https://github.com/AdguardTeam/Scriptlets/blob/master/wiki/about-scriptlets.md#scriptlets
[compatibility-tables-url]: https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree/src/compatibility-tables
[contributing-url]: https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree/CONTRIBUTING.md
[converter-url]: https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree/src/converter
[discussions-url]: https://github.com/AdguardTeam/tsurlfilter/discussions
[license-url]: https://github.com/AdguardTeam/tsurlfilter/blob/master/packages/agtree/LICENSE
[mdn-css-selectors]: https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors
[new-issue-url]: https://github.com/AdguardTeam/tsurlfilter/issues/new
[parser-url]: https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree/src/parser
[validator-url]: https://github.com/AdguardTeam/tsurlfilter/tree/master/packages/agtree/src/validator
[ubo-filters]: https://github.com/gorhill/uBlock/wiki/Static-filter-syntax
[ubo-procedural]: https://github.com/gorhill/uBlock/wiki/Procedural-cosmetic-filters
[ubo-scriptlets]: https://github.com/gorhill/uBlock/wiki/Resources-Library#available-general-purpose-scriptlets