Home

Awesome

<!-- markdownlint-disable -->

 

<p align="center"> <img alt="AGLint" src="https://cdn.adguard.com/website/github.com/AGLint/aglint_512x512.png" width="128px"> </p> <h3 align="center">Adblock Language support for VSCode.</h3> <p align="center"> Supported syntaxes: </p> <p align="center"> <a href="https://adguard.com/"><img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo_128x128.png" width="14px"> AdGuard</a> | <a href="https://github.com/gorhill/uBlock"><img src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo_128x128.png" width="14px"> uBlock Origin</a> | <a href="https://getadblock.com"><img src="https://cdn.adguard.com/website/github.com/AGLint/ab_logo_128x128.png" width="14px"> AdBlock</a> | <a href="https://adblockplus.org/"><img src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo_128x128.png" width="14px"> Adblock Plus</a> </p> <p align="center"> <a href="https://marketplace.visualstudio.com/items?itemName=adguard.adblock"><img src="https://img.shields.io/visual-studio-marketplace/v/adguard.adblock?label=VSCode%20Marketplace" alt="Visual Studio Marketplace Version (including pre-releases)"></a> <a href="https://open-vsx.org/extension/adguard/adblock"><img src="https://img.shields.io/open-vsx/v/adguard/adblock?label=Open%20VSX" alt="Open VSX Version" ></a> <a href="https://github.com/AdguardTeam/VscodeAdblockSyntax/blob/master/LICENSE.md"><img src="https://img.shields.io/github/license/AdguardTeam/VscodeAdblockSyntax" alt="License" /></a> <a href="https://github.com/AdguardTeam/VscodeAdblockSyntax/issues"><img src="https://img.shields.io/github/issues/AdguardTeam/VscodeAdblockSyntax" alt="Open GitHub Issues" /></a> <a href="https://github.com/AdguardTeam/VscodeAdblockSyntax/pulls"><img src="https://img.shields.io/github/issues-pr/AdguardTeam/VscodeAdblockSyntax" alt="Open GitHub Pull Requests" /></a> </p> <!-- markdownlint-restore -->

Table of Contents:

Introduction

This extension adds support for AdGuard, uBlock Origin and Adblock Plus syntaxes to Visual Studio Code, so you can write adblock rules in a convenient way. It also provides a linter to check your rules for errors.

We recommend using this extension if you are working with adblock rules.

You can easily install the update from the Visual Studio Marketplace or the Open VSX Registry:

Here is a screenshot of the extension in action:

<a href="https://cdn.adtidy.org/website/github.com/VscodeAdblockSyntax/screenshot.png"> <img src="https://cdn.adtidy.org/website/github.com/VscodeAdblockSyntax/screenshot.png" style="max-width: 600px" /> </a>

GitHub Linguist support is also available, so you can highlight your adblock rules in GitHub repositories. See GitHub Linguist support for more details. Quick example:

! This is an example rule
example.org##.banner
||example.net/script.js$script,third-party,domain=example.com

Features

In this section we will describe the main features of this extension.

Syntax highlighting

Syntax highlighting is available for AdGuard, uBlock Origin and Adblock Plus syntaxes. Nowadays it is unimaginable to work with code without highlighting, which helps you to distinguish different parts of the code and makes it easier to read.

AGLint integration (linter)

We integrated AGLint into this extension, that makes it able to check your rules for various issues, such as invalid syntax, invalid domains, invalid / incompatible CSS selectors, unknown / incompatible scriptlets, bad practices, etc. For more information about AGLint, please refer to its repository.

AGLint integration is done in the following way:

  1. Extension will search local AGLint installation (if it is installed) and use it for linting. First, it will search for local installation in the current workspace, and if it is not found, it will search for a global installation. This is an ideal behavior, because if you have a local installation, it guarantees that you will use the same version of AGLint, and the results will be the same.
  2. If the extension doesn't find any installation, it will use the bundled version of AGLint, which is included in the extension itself. Usually, it is the latest version of AGLint. The advantage of this approach is that you don't need to install AGLint manually, and you can start using the extension immediately after installation.

[!WARNING] Please note that the linter is under active development, so it may not work properly for some rules. If you find any issues, please report them here. We look forward to your feedback, your help is very important to us!

Configuration

This extension provides the following configuration options:

<!--markdownlint-disable MD013-->
OptionDescriptionDefault valuePossible values
adblock.enableAglintEnable or disable AGLint integration. If disabled, only syntax highlighting and other language features will be available.truetrue, false
adblock.useExternalAglintPackagesIf enabled, extension will search for AGLint installations in the system. If disabled, extension will use its own AGLint installation, which is included in the extension (integrated AGLint bundle). If you have AGLint installed in your system / project, it is recommended to enable this option in order to provide consistent results.truetrue, false
adblock.packageManagerPackage manager to use for searching global AGLint installations. Set it to your preferred package manager.npmnpm, yarn, pnpm
<!--markdownlint-enable MD013-->

GitHub Linguist support

GitHub supports adblock syntax officially via the Linguist library. Our extension provides a TMLanguage file, which is used by Linguist to highlight adblock rules (VSCode highlight also based on this file). This means that if you have a repository with adblock rules, GitHub can highlight your .txt files, if the following conditions are met:

In addition, adblock code blocks can be inserted in markdown files and comments according to the following pattern:

<pre> ```adblock ! Example rule example.org##.banner ``` </pre>

will be rendered as:

! Example rule
example.org##.banner

Ideas & Questions

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

Reporting Issues

If you found a bug or have a feature request, please report it here. Please make sure to include as much information as possible, including screenshots or example rules.

Please note that the highlighter issues on GitHub will not be fixed immediately when we update the TMLanguage in this repository. GitHub's highlighter is only updated after Linguist releases. This process happens roughly every quarter. Before release, Linguist maintainers will update all integrated TMLanguage to the latest version. You can find more information about Linguist's release process here.

Contributing

If you want to contribute to this project, please read the CONTRIBUTING file.

License

This extension is licensed under the MIT License. See the LICENSE 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--> <!--markdownlint-enable MD013-->