# Luakit Documentation / Modules / adblock

# Module `adblock`

Simple URI-based content filter

This is a simple, fast ad blocker module that works by blocking requests to domains that only serve advertisements. It does not currently do any form of cosmetic ad blocking (i.e. element hiding with CSS).

See also: `adblock_chrome`.

## Capabilities

- You can allow specific content to be loaded if it is inadvertently blocked: simply add whitelisting rules formed by `@@` and the pattern to allow.
- Supports multiple filter list files.
- Filter files can be enabled, disabled and reloaded from disk without restarting luakit.
- A configuration chrome page is provided by `adblock_chrome`.

## Usage

- Add `require "adblock"` and `require "adblock_chrome"` to your `config.rc`.
- Download AdblockPlus-compatible filter lists to the adblock directory. Multiple lists are supported. EasyList is the most popular Adblock Plus filter list, and can be downloaded from https://easylist.to/.
- Filter lists downloaded to the adblock directory must have a filename ending in `.txt` in order to be loaded.
- Filter lists need to be updated regularly (~weekly), use cron!

## Troubleshooting

If ad blocking is not working as expected, the easiest way to determine what is happening is to set the appropriate log levels to `debug`:

If a filterlist is not being loaded for some reason, start luakit with the following:

    --log=lua/lib/adblock=debug

If a filterlist is not behaving correctly, by blocking too much or too little, start luakit with the following:

    --log=lua/lib/adblock_wm=debug

## Files and Directories

- All filterlists should be downloaded to the adblock data directory. By default, this is the `adblock` sub-directory of the luakit data directory. All filterlists must have a filename ending in `.txt`.

## Functions

### adblock.load (reload, single_list, no_sync)

Load filter list files, and refresh any adblock pages that are open.

#### Parameters

- reload
  Type: boolean
  `true` if all subscriptions already loaded should be fully reloaded.
- single_list
  Type: string
  Single list file.
- no_sync
  Type: boolean
  `true` if subscriptions should not be synchronized to the web process.

### adblock.list_set_enabled (a, enabled)

Enable or disable an adblock filter list.

#### Parameters

- a
  Type: number or string
  The number of the list to enable or disable.
- enabled
  Type: boolean
  `true` to enable, `false` to disable.

### adblock.whitelist_domain_access (domain)

Whitelist accessing a blocked domain for the current session.

#### Parameters

- domain
  Type: string
  The domain to whitelist.

## Properties

### adblock.subscriptions

Type: table
Read-only
The set of ad blocking subscriptions that are active.

### adblock.rules

Type: table
Read-only
String patterns to filter URIs with.

### adblock.enabled

Type: boolean
Default: true
Read-write
Whether ad blocking is enabled. Modifying this value will modify adblock state; setting it to `true` will enable ad blocking, while setting it to `false` will disable ad blocking.

## Attribution

#### Copyright

- 2010 Chris van Dijk
- 2010 Mason Larobina
- 2012 Plaque FCC