Watched Words Reference Guide

Looking for information about Watched Words? You’re in the right place!

:bookmark: This is a reference guide for describing how the Watched Words page functions and the different types of action types you can use to block specific words on a Discourse site.

Watched Words

As of Discourse v1.9, you can setup Watched Words to take actions based on words found in a topic or post (located at .../admin/customize/watched_words ).

There’s a max of 2000 words per type of action.

On all actions, * can be used as a wildcard, and there’s an option to select if the watched words are case-sensitive.

By default, the watched words are hidden. Checking the “show words” checkbox will display them and allow you to delete them. Using the search field will also reveal any matching words.

Lists of Watched Words can be uploaded in bulk using the “Add from File” button, and a list of Watched Words for any action type can be downloaded from Discourse with the “Download” button. CSV is the required file format for uploading watched words in bulk.

All actions also have a “Test” button that can be used to test if a specific word or phrase contains any watched words.

Example of a matched watched word phrase

Example of a phrase with no matches

Action Types

The Watched Words page allows you to take the following types of actions on matched words:

:information_source: A Watched Word can only exist in one action type list. If a duplicate word is added to a second list it will be removed from the previous list.


Prevents topics or posts containing these words from being posted at the time they are submitted by blocking the entire topic / post. The user will see an error message when they try to submit their post.


Allows posts containing these words, but replace the words with characters that hide the censored words. Censored words will be replaced with blocks. (Ex: ■■■■■■■■)

Require Approval

Posts containing these words will require approval by staff before they can be seen. Upon submitting a post with a word with this action type, the post will be hidden until staff reviews it.


Allows posts containing these words, but flags them so moderators can review them. A post with a flagged word will appear normally but be submitted for review. The reviewer will have various options:

If they hide the post, it will still be viewable but will look something like this:

Clicking on the ‘View ignored content’ link will show the full contents, but still in the ‘post-hidden’ state.

If they choose ‘Keep Post,’ or choose ‘Disagree’ from the options, the post will look like this:


Replaces words in posts with links. More commonly used to replace common words with links to specific topics or external URLs instead of censoring words.

If no Link URL is selected when adding a word to this type of action, the homepage of the Discourse site will automatically be used as the link to replace the word.



Replaces words in posts with other words. Cannot be used to replace words with links.

If no Replacement word is selected when adding a word to this action, the word will be removed from the post, but no word replacement will take it’s place - the word will disappear from the post, and the post will be allowed to be submitted (Not Recommended).



Automatically tags topics with these words based on first post in the topic. One or more tags can be added for each word included in this action.


A tag must be included when submitting a word with this type of action, otherwise you will receive an error.


Also note that when tagging topics with a watched word, the word must be included in the topic at the time the topic is posted in order for the topic to be correctly tagged. Editing a topic after it has been created with a watched word for a tag will not add the tag to the topic.


First posts of users containing these words will require approval by staff before they can be seen and the user will be automatically silenced. A user who uses a “silence” word on their first post will be silenced and the post be will sent to the moderation queue

Regex Expressions

For information about using Regex Expressions with Watched Words see:
Using Regex with Watched Words



1 Like

I was thinking that. Probably if you are hosting with discourse you need to reach out to them.

Apologizes, that should have read:

If your site is hosted with Discourse, please reach out to if you would like to enable this setting.

OP has been updated.

Sorry for any confusion there :slightly_smiling_face:


Would adding a “description” behavior on watched words, such as:

be a #pr-welcome?

I’ve started using linkification of some terms and acronyms on my forums, but I feel it’s not the best solution, and I need more quick explanations of acronyms than links.

The best would be some sort of popup on hover (touch on tactile screens) with a very short description/explanation, and an optional link, but I supposed that would be lot of work.

My gif is using GitHub - metabrainz/discourse-abbrify-words: Discourse theme component for automatically adding <abbr> to abbreviations and acronyms which is heavily based on GitHub - discourse/discourse-linkify-words: theme to auto linkify urls in discourse.

Since abbrify-word isn’t actively maintainted, I can’t use it for my purpose.

1 Like

I can’t seem to get links to work at all for our new forum. I put in a word, and a link, and it passes the test. But there are already posts on the site with this keyword in them, and they aren’t being converted to a link. Is there something more that needs to be done to enable this feature than just inserting a word and a link?

It will only work on new instances of the word. To linkify the old ones you’d need to rebake those posts.

I JUST figured that out, they need to be new or edited. Thanks!


There’s also an option to ‘Rebuild HTML’ in the post wrench menu which will rebuild them with the new rule in place. :+1:

To do a significantly large amount you would need to perform a rake task on the server. You can read more about those in Administrative Bulk Operations

Could I make a request that this optionally allow for targeting a new browser tab? When linking to a totally external destination, this would be nice to be able to choose on a per-link basis (or maybe to be able to set a default globally as well)

I can understand why most watched word options are exclusive, e.g. if you’re blocking a word then you don’t want to censor or tag the post because of it. However, tagging and linking seem different and I think would benefit from being allowed on the same word.

In my forum users make regular references to a variety of pieces of hardware and software. I already use those product names to tag the posts. It would also make sense to add links to the names so that people can find the third-party website corresponding to the item but that can’t be done at the moment. Is this a restriction that could be/might be removed in future?