5 ! --- [BOOST]WEB SITES ---!

26 ! --- [BOOST]BLOG ---!

40 ! --- [BOOST]BLOG BY PROFESSIONAL PLAYERS ---!

54 ! --- [BOOST]TWITTER(X) ---!

62 ! --- [BOOST]NEWS SITES ---!

70 ! --- [DOWNRANK]NEWS SITES ---!

78 !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

79 ! Goggles are simple, self-contained text files which can be hosted in Github or

80 ! Gitlab. These files contain instructions allowing you to tell Brave Search how

81 ! you'd like your results to be ranked. You can target specific URL patterns

82 ! (and, soon, website titles and other aspects of Web pages) and indicate how

83 ! their ranking should be altered (e.g. boosted, downranked, or completely

84 ! discarded from the results).

86 ! A Goggle source file consists of instructions, one per line. Empty lines, or

87 ! comments (starting with an exclamation mark: '!') are ignored. If your Goggle

88 ! contains invalid instructions, submitting the Goggle on Brave Search will fail

89 ! and you will get feedback regarding what went wrong.

91 ! You probably already noticed the header of this file which contains some

92 ! metadata about your Goggle, such as: name, description, public and author.

93 ! These are *mandatory*.

95 ! Additionally, you can specify the following optional metadata attributes:

96 ! * homepage — specifies a homepage URL displayed on your Goggle's profile.

97 ! * issues — specifies a URL where users can report issues for your Goggle.

98 ! * transferred_to — Allows to transfer ownership of a Goggle.

99 ! * avatar — specifies a *valid* HEX color code for your Goggle.

100 ! * license — specifies the license of a Goggle's instructions.

102 ! The simplest instruction is a plain-text pattern which can be found in URLs.

103 ! The following would match any search result whose URL contains the pattern

104 ! as-is:

105 ! /this/is/a/pattern

107 ! It is also possible to use some limited "globbing" capabilities such as the

108 ! '*' character which will match zero, one or more characters (note: the number

109 ! of wildcards allowed in a given instruction is limited):

110 ! /this/is/*/pattern

112 ! The special character '^' can be used to indicate that an URL delimiter such

113 ! as '/' or end-of-url can be matched. More specifically, '^' is equivalent to

114 ! the regexp: [^\w\d._%-]|$

115 !

116 ! This means that it can match either the end of the URL or any character that is

117 ! not a letter, digit, dot, underscore, percent sign or dash. Here are a few

118 ! examples of characters that are matched by '^': / (slash), = (equal),

119 ! [ (bracket), : (colon), etc.

120 !

121 ! In practice, you will usually want to use '/' (or any other specific

122 ! separator like '=' or '?') most of the time in your patterns, except at the end

123 ! of a pattern in cases where you want to be a little bit more generic, and

124 ! express that your pattern should be either matching at the end of the URL or be

125 ! followed by a separator and then arbitrary URL components.

126 !

127 ! For example, |https://example.org^ will match: 'https://example.org',

128 ! 'https://example.org/' or 'https://example.org/path'; but it will *not* match

129 ! 'https://example.org.ac', which is also a valid domain name starting with

130 ! 'https://example.org'.

131 !

132 ! Another example, /foo.js^ will match: 'https://example.org/foo.js',

133 ! 'https://example.org/foo.js?param=42', 'https://example.org/foo.js/' but it

134 ! will *not* match 'https://example.org/foo.jsx' (because it is not followed by a

135 ! separator).

136 !

137 ! Also note that the maximum number of carets allowed in a given instruction is

138 ! limited.

139 ! /this/is/a/pattern^

140 ! |https://example.org^

141 ! /foo.js^

143 ! By default, a pattern can match anywhere in the URL, but there are specific

144 ! characters which can be used to indicate prefix or suffix matches: we call them

145 ! "anchors".

146 !

147 ! The '|' character can be used at the beginning or end of an instruction to

148 ! indicate anchoring. The following instruction will match a prefix of the URL:

151 ! The following will match a suffix of the URL:

152 ! /some/path.html|

154 ! Both can be used at the same time:

155 ! |https://brave.com|

157 ! Additionally, each instruction can specify a list of options, following the

158 ! '$' character and separated by commas (','). Options can be used to more finely

159 ! target specific search results, or to indicate how a matched result's ranking

160 ! should be altered.

162 ! The most basic option is 'site=', which can be used to limit a instruction to

163 ! a specific website, based on its domain. Options can be specified on their own

164 ! (e.g. if you want to target any page of a site) or in conjunction with a

165 ! pattern:

166 ! $site=brave.com

167 ! /blog/$site=brave.com

169 ! Another set of options can be used to indicate what you want your instruction

170 ! to target. By default any instruction will apply to a URL, but we will add the

171 ! ability to match other aspects of a page too, in the future:

172 !

173 ! web3$inurl

174 ! web3$intitle

175 ! web3$indescription

176 ! web3$incontent

178 ! Finally, you can specify an 'action', which indicates how the ranking of a

179 ! matched result should be changed by your instruction. This is the mechanism

180 ! through which you can customize the ranking of results to your liking. You can

181 ! use one of three possible actions in your instructions, and by default, any

182 ! instruction without an action will be considered as 'boost':

183 ! /r/brave_browser/

184 ! /r/brave_browser/$boost

185 ! /r/brave_browser/$boost=2

186 ! /r/brave_browser/$boost=3

188 ! The value associated with the option indicate the 'strength' with which you

189 ! want to alter the ranking (note: that it is currently limited to a maximum

190 ! value of 10). It can be used to boost results differently, even inside of the

191 ! same Goggle (e.g. some results should be favored more than others).

192 !

193 ! You can also downrank results:

194 ! /r/google/$downrank

195 ! /r/google/$downrank=2

196 ! /r/google/$downrank=3

198 ! Last but not least, you can discard results completely:

199 ! $discard,site=idontwanttobepartoftheresults.com

200 ! /this/is/spam/$discard

202 ! Individually, each instruction can either target a very narrow set of pages (or

203 ! even a single page), or a wider range of them, to apply reranking to a bigger

204 ! set of results. In combination, hundreds or more instructions can allow you to

205 ! express complex reranking functions.

207 ! Although the Goggles language could express instructions to search through a

208 ! small set of websites or act as a blocklist, Goggles really shine when used to

209 ! express boosting and downranking across many domains and pages.

211 ! Goggles also impacts the behavior of features such as Discussions and News or

212 ! Videos clusters, giving you full control on your search experience.

213 !

214 ! We are already using Goggles internally, and we can't wait to see what you will

215 ! do with them!

217 ! To learn more about Goggles, we recomend that you read the "Learn by example"

218 ! section of our "Getting Started" page here: https://github.com/brave/goggles-quickstart/blob/main/getting-started.md#learn-by-example