Last updated: 21st of July 2018
Are you wondering about how to create your own adblock list? Do you want to backup your extension’s custom filters, or do you perhaps want to cloudshare your filters between multiple browsers and systems? Here is a bare-bones explanation of how to make one.
1) Find a place to upload and show raw .txt files
This part is actually much harder than it sounds like, because most cloud services do not readily allow to view raw .txt files due to security concerns, as a .txt could have functioning code written in them. Even services like Google Drive and OneDrive, while one can save .txt files to them, use a distanced text reader to show such files in web browsers, which is insufficient for adblock lists.
Your best bets are either GitHub, Gitlab, or Dropbox. I have insufficient knowledge of the Dropbox method at the time of writing, so for now this guide will assume that you’ll pick GitHub.
G-2) Making an online repository
A repository refers to a place where code is stored, usually online.
Make a GitHub account. Then go to the repository creation process, pick a name for the repo, and click on the Create repository button. Note that you are essentially forced to pick Public as your privacy option, both to avoid paying money for a service that may be new to you, and in case you want to make topical lists that are intended for public use one day.
G-3) Making the text file
In the upper right in your new repository, click on a small button that says Create New File. In the field in the upper left that says Name your file…, write a good name for it, and add .txt to the end of the name.
4) Adding entries to and formatting the adblock list
Since you’re likely still inside the file editor, let’s begin with the best part.
The first line should be
[Adblock Plus 2.0]. This is necessary in order for many adblocker extensions to get to know that this is an adblock filter list.
The 2nd and 3rd lines are optional, so to say, but they are highly advantageous. They should be:
! Name: [What you want to name your adblock list.]
! Expires: [How often you want for the extensions to auto-check for changes to the list; can be written as “n hours”, “1 day”, or “n days”.]
Presuming that you already have a fair few filters in your custom filters (or in “My filters” as it can sometimes be called), paste them verbatim into the editor, below the above lines. After having done these steps, it should look something like this:
Then click on the green button at the bottom that says
Commit changes to save the file. To commit, means in computer lingo to change the code of a project.
5) Subscribing to the raw .txt file
While at the completed file, click on a button in the upper right that says Raw. This will bring you to a flat and raw view of the file that you just made. If you chose GitHub to host the .txt file, the URL should begin with https://raw.githubusercontent.com/ (…).
Go to your adblock extension, find a field that is called something á la “Import lists” or “Custom lists”, and paste the URL into it. If the list was made correctly, it should show up in the extension’s menu as having at least 1 entry (Anything more than “0 of 0”, really), and in most cases show its in-file name as its title. If it does at least one of those two things, then congratulations. You have succeeded at making your very own adblock list!
If it shows up in the adblocker as a non-titled URL and with 0 filters, then either the list or the URL that you pasted was made incorrectly, and some fine-tuning will need to be done on it.
It is considered to be good behaviour to do things like adding a homepage link to the file, to add an open-source licence to both the file and the repository, and to add a version number so that the list’s users (incl. you) can easily see if your extension is using the newest version of the list or not.
But none of those things are required, and especially not for lists that are aimed for personal use. So if you just want to do this easy and smooth, you can skip those things for now, and instead learn about them later on.
uBO) Special notes for uBlock Origin users
uBlock Origin, and probably also Adguard, differs a little from the more simple adblock extensions (e.g. Adblock Plus and AdBlock) out there. They can use files that lack filename extensions, they do not require lists to have
[Adblock Plus] as the first line, and they don’t accept “n hours” as an
! Expires time (They’ll round it up to 1 day).
Moreover, uBlock Origin adds situational notes to every custom filter, that are rarely necessary for most types of adblock lists. If you desire to remove situational notes and blank lines, paste the filter lines into a program that can sort lines alphabethically (I recommend Sublime Text), press F9 to sort the lines, and mark and remove all the non-filter lines. Then paste the cleaned-up entry list into the online .txt file.