📗 Discourse Admin Manual

manual

#1

Content

1. Working with content

2. Working with categories

3. Working with tags

4. Working with users

5. Understanding notifications

6. Other aspects


1. Working with content

1.1. How to delete an unwanted topic?

Click “Wrench icon → Delete topic” below the topic.

Deleted topics are retrievable at https://edgeryders.eu/?status=deleted (reference).

1.2. How to see the deleted content written by a certain user?

  1. As an admin user, visit the user’s profile page (example: user matthias).
  2. Click the button “Expand”.
  3. At the top, you’ll see “[number] deleted posts”. Click that.
  4. A list will appear with all content this user wrote that was deleted, also showing in the right side by whom (the user, or an admin).

1.3. How to post to the official blog?

The official blog is a collection of slightly better editorialized posts about Edgeryders as a community and a company. It is accessible from the Company drop-down menu on the top right.

In the edgeryders.eu website, the official blog is not a category but a view of the Discourse tag blog. Admins and moderators can include any topic for being published on the blog. To do so:

  1. Write the post. Remember: you are aiming for an audience beyond that of the community, so do not take too much for granted. If you are making a point that needs some background information, provide it. A good form is a one-sentence mention plus a link:

    Back in 2016, we had been active in some project. The point was to achieve this and this other goal. We succeeded, but we have never been completely happy for this reason. Now, we are moving on to the next level.

  2. Choose a category for it. A blog post can be in any category. If you are writing an update about a project, the best is probably to write within the project category. If the project has no category or lives in a private one, #campfire is a good fallback position, plus assigning the ‘project-*’ tag to the topic that corresponds to the project.

  3. Add a nice image. Posts with pictures are always nicer and more effective.

  4. Add the blog tag. This is done in the “choose optional tags for this topic” field in the edit screen. The tag tells the platform that your new topic should be visualized in the blog. Note that only moderator and administrator users can use this tag, so you might have to ask one of them to do this for you.

  5. Make sure the image preview displays correctly. The blog view takes the first picture in the post and displays it as an “ultrawide” preview image in format 690×150 px. If this results in a good preview of your picture, no need to do anything. If it looks bad (maybe it cuts people’s heads off) do the following:

    1. With an image editor, crop your image (or another image) to proportions 690:150 (for example 690×150 px or 1380×300 px etc., as large as it fits for the excerpt of your source image that you want to show as the preview).

    2. Upload it at the top of your post.

    3. Edit the line of code relating to the uploaded image, so that it ends with width="1" height="1">. This will “hide” the preview picture in the full topic view by displaying it in 1×1 px size. A full line will look something like this:

       <img src="/uploads/default/original/2X/1/136c0f.jpg" width="1" height="1">
      
    4. The ultrawide version of the image that you provided may also look good in your main text (so you can delete the version uploaded earlier). But in case you want to display it in full height (not in the preview format) on the topic’s page, you can keep both versions. The code will then look something like this:

       [some text of the topic might be here, before the images]
       <img src="/uploads/default/original/2X/1/136c0f.jpg" width="1" height="1">
       <img src="/uploads/default/original/2X/f/fedfbc1.jpg" width="690" height="388">
       [remaining text of the topic]
      

      The first line displays the ultrawide picture only in the blog view; the second one display the full height image in the main text. Remember you have to upload both the original and the cropped file, as they are images with different content now.

2. Working with categories

2.1. How to find the ID of a category?

You need the category if you want to create a permalink to the category under “Admin → Customize → Permalinks”. While topic IDs appear at the end of URLs, it’s not that simple with categories. But here is a workaround:

  1. Go to the category’s page (that is, click on its name on the Categories overview page).
  2. Click the “magnifying glass” icon to open the search form.
  3. Check the “Search the … category” checkbox.
  4. Enter any search term and press the Enter key. This will bring you to the advanced search form.
  5. Here, you will see the search field with the parameters of your one-category-only search. For example, “your-search-term category:41”. The number is your category ID.

2.2. How to convert a category into a topic?

This is not possible with any dedicated Discourse feature. You have to do the following steps manually:

  1. Edit the “About the … category” topic in the category and copy&paste its content to a new topic in a new category.

  2. Adjust ownership for the topic now containing the “About the … category” content: click “three dots menu” (below the topic), then “wrench icon” (for “Admin actions”), then “Change Ownership”.

  3. Assign all topics in the category to other categories. As a moderator / admin:

    1. Click the “list icon” on the top left of the list of topics in this category. A list of checkboxes will appear, and some buttons.
    2. Select some (or to select all, scroll till you reach the bottom, then click “Select All”).
    3. Click the “wrench icon” in the top right, select “Bulk Actions” from its menu.
    4. Execute the “Set Category” bulk action.
    5. Repeat as needed until no topics are left in this category. (Except for the special “About the … category” one, which you can’t move even if you try. We copied over its content above already.)
  4. Delete the category. (Click “Edit” on the category overview page, then “Delete category”.)

2.3. How to create a new top-level category for a project?

For the Edgeryders top-level project, we use a few custom-made Discourse features and conventions to make it look the way it does. Here’s how. Note that, to change the category structure and settings, you need to be a Discourse administrator (being moderator is not enough).

  1. Create a new top-level category for the new project.

  2. Configure a category color, based on the main color of your project’s logo, and add it to the allowed category colors in Discourse. By convention, the category color and logo color for project categories on edgeryders.eu should be a shade of blue. Configure that color in the settings dialog of your category.

  3. Upload a category image. From your project’s logo, prepare a category image (150×150 px in size, PNG format, transparent background). Then go to tab “Images” of the category’s settings dialog and upload that image.

    :exclamation: This step is important because only when a category logo is present, a category description will be shown at the top of the category’s page (resp. sub-category’s page). As a counterexample, see the “Documentation & Support” category.

  4. Configure the way subcategories are shown. In the settings dialog of your category, go to tab “Settings” and enable “Show subcategory list above topics in this category.” with “Subcategory List Style: Boxes”. This is our convention for project categories.

  5. Edit the category description – it’s in the auto-generated topic “About the [category name] category”, always visible at the top of the category’s topic list. There:

    • Add a one-sentence paragraph at the top, separated by an empty line. This will be used as the short-form category description in the /categories overview page, on the category’s own page, in the category dropdown list etc…

    • Add more content below the first paragraph to explain the purpose and content of your category in detail and to engage users. This can include images, embedded videos etc…

    • Select all text after the first paragraph, then click “gear icon → Hide Details” in the editor to wrap it into a [details=Show more] … [/details] tag. This will show the first summary paragraph and a “Show more” foldout link on the category’s page (and, as a side effect, also when viewing the “About the [category name] category” topic directly).

      Showing all “About” topic content on the category’s page is a custom feature we added to create a more engaging category page. In standard Discourse, the category’s page would only show the summary paragraph. While we use the [details=Show more] … [/details] tag to hide content dynamically, still keeping it accessible on the category’s page.

  6. Unlist the “About the … category” topic. Either from the “wrench icon” menu on the topic’s page, or from the bulk actions “wrench icon” menu on the category’s list of posts, after selecting only this one. This will hide the topic for all normal users, as it’s just redundant content for them, all shown at the top of the same category page already. Because the topic stays pinned, admin users however still see it at the top of the list, easily accessible for editing.

  7. Change the ownership of the first post in the “About the … category” topic to user “edgeryders”. Usually done to have a more uniform appearance as categories and not distract users by presuming a connection between categories and individual users. There might be exceptions of course, where such a connection exists, and in that case the ownership perhaps should not be touched.

  8. Create the subcategories. Follow roughly the same steps as above for creating top-level categories. Some option will not be available. But in particular, the option to create an unfoldable category decription should also work for subcategories.

2.4. How to create an access restricted category?

This is treated in its own topic here:

3. Working with tags

We need to use tags this since we want to employ tags as additional ordering scheme to tag by “aspects of wellbeing” etc… Tags in Discourse can be assigned to topics, but not individual posts. Recent versions of Discourse have made tags a core feature (info).

3.1. How to tag content in bulk?

  1. Go to any suitable list of content (for example, a category page).
  2. Click “list icon” in the top left corner of the actual content table. (Mouseover text is “toggle bulk selection of topic”.)
  3. Select all content items to tag, using the checkboxes that appeared. (If you click “Select All”, it will only select the visible content on the page, so click to reload more until you reach the bottom if you want top operate on the whole category.)
  4. Click “wrench icon” in the top right, then “Append Tags”.
  5. Select existing tags or enter new tags, then confirm with the “Append Tags” button.

3.2. How to remove a tag?

  1. Go to the global list of tags.
  2. Click on a tag.
  3. Click the “trash can” icon to delete the tag. (The content tagged with it will be kept, of course.)

Since the /tags page lists only tags used at least once, not-in-use tags cannot be deleted this way. Still, they clutter the namespace of proposed tags when tagging content. To delete them, construct their URL in the form https://edgeryders.eu/tags/{tagname}, then proceed as above.

3.3. How to know what tags are for what purpose?

Here’s a short reference (to be extended):

  • Tag blog: Used for all topics that we want to give prominence in the official Edgeryders blog (“Company → Official Blog” in the menu). Assigning this tag automatically adds it to the blog, but the tag can only be used by Discourse moderators and admins. This includes all topics that were in the “Blog” group of our Drupal-based platform. You can subscribe to our blog with your RSS reader, as Discourse has RSS for everything. In this case, it’s https://edgeryders.eu/tags/blog.rss.

  • Tags for project content. We use Discourse in a way that involves frequent re-categorizing of content, depending on our needs. Also, project-based categories are regularly dismantled after the end of the project, and the content is sorted into broader categories, to keep the numbers of categories small. In order to still keep together project content, we use the “project-*” tags, made from the prefix and the project’s name. It is not necessary to tag project content while there is a project category, only when dismantling that.

  • Tags for the wellbeing ontology. We did not start with this tagging, but the current proposal is to use a naming scheme with a “wellbeing-” prefix, for example “wellbeing-food”. The exact prefix is undecided though. Maybe “goodlife-*”?

  • Tags for Drupal content types: Upon import from Drupal, tags were assigned to keep track of the original node’s content type. These are: task, wiki, document, event, challenge_response, group, minisite_page, journal, page, infopage. These tags will eventually be removed, once we are sure we don’t need them to finish Drupal-to-Discource migration related tasks. Tag post has already been removed, as posts did not have any special features to be aware of.

  • Tags for ethnographic coding. Tags will be used by Open Ethnographer for interfacing to Discourse. To be updated once OpenEthnographer is available within Discourse in early 2017-09.

3.4. How to filter a list of tagged topics also by category?

This is a “hidden” feature without a way to do this in the graphical interface, because we disabled the “tag” filter on category pages. So this feature is used by constructing a URL in the following way, as also documented here:

https://edgeryders.eu/tags/c/{category-slug}/{tag-name}

For example:

https://edgeryders.eu/tags/c/openvillage/event

Note that the same list results can also be shown by constructing a search query with tag and category filters set, but the format of the output will be different. Example:

https://edgeryders.eu/search?q=tags%3Aevent%20%23openvillage

4. Working with users

4.1. How to be notified about new user signups?

How to be notified. To be notified about new user signups, simply subscribe to topic “New members on edgeryders.eu”. Use the “Tracking” or “Watching” notification level, and updates from this topic will be included in your regular Discourse notifications, both on the platform and via e-mail. Discourse will add one comment to this topic whenever a new member registers on edgeryders.eu. (Note, when somebody only registers on our login site communities.edgeryders.eu but never logs in to edgeryders.eu, this will not trigger a notification.)

How to not be notified. By default, a user will not be notified about any updates to this topic, until they choose to as described above. (This is implemented by setting this topic to “Unlisted”. Unlisted topics do not appear in the “Latest” tab for anyone, or in the “New” tab of people who subscribed to this topic’s category. This is better than requiring everyone with access to this topic to set it manually to “Muted” in order to not get notifications, but basically has the same effect.)

Access to the user signup feed topic. This topic is in our “Documentation & Support → Unpublished” category, so it is not accessible to the public. This allows to link to this topic from a public topic without giving access to it; for example the link above in this manual.

How to set this up for your own Discourse installation.

  1. Install our plugin edgeryders-signup-notification.

  2. Create a topic that should act as the user signup feed, place it in an access protected category, an set it to “unlisted” (see above for the reasons).

  3. Enter the topic ID of your signup feed topic in the settings of the edgeryders-signup-notification plugin.

4.2. How to welcome new members on the platform?

See topic “Welcoming new members” (access restricted).

4.3. How to see user statistics?

The platform serves a screen with the full history and participation stats for each user. Example, for username moe: https://edgeryders.eu/u/moe/summary . There is also a summary version in the Users item in the hamburger menu. And it is wonderful to use: filterable, sortable by any statistic with one click.

There are obvious data structure implications. Implicitly, a network is being induced where the users are nodes, and there are two layers of edges: A likes-the-content of B and A replies-to-the-content-of B. This means that, in the data structure, there is a full users-to-content bipartite network. Would like to discuss this with @matthias in the not-too-distant future.

4.4. How to obtain data with user consent for research use?

The Edgeryders platform has a feature called an ethical consent funnel. This serves to users trying to post for the first time a popup form that we call the “consent funnel”: it asks users to answer some questions before they are able to post in certain categories. They can only proceed past the form when they have answered its questions correctly. We interpret this sequence of events as follows: the user has given informed consent to participating in a research project with Edgeryders, and has understood the nature of her part in the exercise.

Accessing these data requires API access. See the API documentation.

4.5. How to delete a user account?

Please follow the hints given in our website manual, section “4.1. Deleting your account”.

In some cases, you have to temporarily adjust the following Discourse settings to be able to delete all posts of a user at once, and then the user:

You need to be administrator (not just moderator) to be able to do this. Remember to re-set these settings to their previous values afterwards, as they serve as safeguards against harm done accidentally or intentionally by staff users.

4.6. How to fix a user’s signup problem?

When somebody tries to sign up but, sometimes they get stuck, most likely because the e-mail address validation e-mail gets caught up in their spam filter. In these cases the problem can be fixed with the help of an admin of communities.edgeryders.eu, as shown below.

These instructions have been tested with current Chrome (Chromium) and Firefox in 2019-02.

  1. Find and contact a communities.edgeryders.eu admin via this list for help, or if you are that admin yourself, proceed as below. (Being a moderator on communities.edgeryders.eu is not enough as these cannot use the “Impersonate” feature.)

  2. Open an “incognito window” (Chrome) or “private window” (Firefox), and perform all the following actions with browser tabs in that window until the instructions say to go back to your normal browser window.

    (You could keep working in your normal browser window, but would be logged out at the end of the process. Using an incognito window prevents that, as it allows a parallel login.)

  3. Log in as admin on communities.edgeryders.eu.

  4. Find the record of the user with the incomplete signup under “☰ → Admin → Users → New”. Users which did not yet successfully validate their e-mail address are shown in gray in that list.

  5. Click on the user record in that list, make sure the user’s e-mail address does not contain a mistake, and then click “Permissions → Activate Account”.

  6. At the page bottom, click Impersonate. This will log you in as that user until you log out or close the incognito / private window.

  7. In a new browser tab, visit the Edgeryders Communities platform which the user wanted to join, such as edgeryders.eu.

  8. Click “Log In” in the top right. This will immediately log in the user you impersonated on communities.edgeryders.eu. Since it is their first login there, it will create the user’s account and take over their username, name, e-mail address and profile picture from communities.edgeryders.eu.

  9. Log out as the impersonated user, or just close the incognito / private browser window.

  10. Back in your own normal account on an Edgeryders Communities platform such as edgeryders.eu, you can now @mention the new user or send them a message, because you created their account on this platform with admin tools. The system will send them an e-mail about the @mention or message, but of course if the user has a badly configured spam filter that e-mail might get caught up there again.

The above process can also be used to create an account for a user who did not even attempt to sign up themselves. The admin user would simply simulate the user filling the signup form, and then proceed as admin user for account activation and creating the connected account on an Edgeryders Communities site. When doing this, make extra sure to use the right e-mail address, as the process allows to create accounts (and cause e-mails from these accounts) for people who never wanted one.

5. Understanding notifications

5.1. Notification types and places

Notification types. To understand Discourse notifications, we distinguish the following two different broad categories of notifications. (Discourse does not use this concept in their own manuals – we made it up.)

  • content notifications: Any notification about new content (topics and posts) to which a user is somehow subscribed. These show up on-platform in the “Unread” and “New” sections and sometimes by e-mail.

  • event notification: Any notification about a more specific event than simply “new content”, namely: direct reply, quotation, @mention, likes, invitation to a topic, edit of your post, private message, new topic, link to your topic. These show up on-platform as a blue bubble on the user menu and as an entry inside it, with an icon corresponding to the event type. They also sometimes show up as e-mails.

Notification places. As already briefly mentioned above, notifications can appear in different places:

  • user menu: The place where event notifications are shown on the edgeryders.eu platform: as little blue bubbles in the user menu, which always correspond to an entry in that user menu.

  • counters: The place where content notifications are shown on the edgeryders.eu platform: as counters in the user’s “New” (for new topics) and “Unread” (for new replies) sections in the frontpage and hamburger menu.

  • e-mail: An e-mail sent to the user’s registered e-mail address. One e-mail can contain one event notification, or one or more content notifications (aggregated according to the “Activity Summary” settings in a user’s account).

  • desktop: Desktop notifications. Not treated in more detail below, as they are simply a copy of event notifications that appear in the user menu. (Content notifications do not appear as desktop notifications, ever.)

    Desktop notifications appear only in a browser if the user enabled them by visiting the user settings form with that browser.

Trigger actions, notification types and notification places are connected by rules that govern what notifications Discourse will shown when and in which place, as detailed below.

5.2. Trigger actions and the notifications they create

Which notifications are sent for which action is influenced by several factors. The most important one is the notification level configured per user for topics, categories and tags. But there are other factors as well ­– here are the details:

  1. When you create a new topic, Discourse creates:

    • Content notifications: For users who subscribed to the topic’s category (which could be “Uncategorized”) with level “Watching First Post” or higher, or to any of the tags that you added to the topic with level “Watching” or higher.

    • Event notifications for “new topic”: For the same users who got the content notifications already. This is the only case where content notifications also result in an associated event notification – the same behavior does not apply for replies to content a user is subscribed to, only for the “new topic” case!

    • Event notifications for “quoted”: For users you quoted in the topic, if any. [TODO Check if this also applies when a user set the topic’s category or any of its tags to subscription level “Muted”. Probably it does. Also find out if and how user muting influences this notification.] If these event notifications can lead to an e-mail depends on the user setting “user menu → Preferences → Email → Send me an email when someone quotes me, replies to my post, mentions my @username, or invites me to a topic”. It is enabled by default.

    • Event notifications for “linked”: For the author of the post you linked to, if any. This notification will be shown on-platform, not by e-mail. [TODO: Check if link notifications can only appear for posts that started a topic, or indeed for all posts. If necessary, also adapt this below where the same event is treated for editing post content. Also find out if and how user muting influences this notification.]

    • Event notifications for “@mention”: For users you @mentioned in the topic, if any. The same restrictions as for the “quoted” event apply, see above.

  2. When you post in an existing topic, Discourse creates:

    • Content notifications: For users who subscribed with level “Tracking” or higher to the topic itself, to the topic’s category, or to any of its tags. These subscriptions form a hierarchy: if the user muted the notifications of the topic’s category or any of its tags, she will still get the notification if she overrode that setting on the topic level explicitly.

      Subscribed users also include those who have been reading the topic for some time. as governed by the setting “Automatically track topics I enter” in “user menu → Preferences → Notifications”. The default value is “after 3 minutes”.

      Subscribed users also include the topic’s original author, who is automatically subscribed in level “Watching” (the highest) to the topic she created, until manually overwriting that. When transferring authorship of a topic to another user, it does not affect the notification level set for the topic by the the original or the new author.

    • Event notifications for “direct reply”: For the user to whom you replied. If you reply to the first post or whole topic, it counts as a direct reply to the topic author. [TODO: Confirm that e-mails are only sent for direct replies, not for indirect ones.]

    • Event notifications for “quoted”: (For details, see above for the same event.)

    • Event notifications for “linked”: For the author of the post you linked to, if any. This notification will be shown on-platform, not by e-mail.

    • Event notifications for “@mention”: (For details, see above for the same event, and about auto-tracking of topics in muted categories and tags as documented for “quoted” events above.)

  3. When you like a post, Discourse creates:

    • Event notifications for “Like”: For the author of the post you liked, but only if this is allowed by the user setting “Notify when liked”. Note that wiki posts are not treated specially: only the user shown in the avatar icon is considered the author of the post who will be notified about likes.
  4. When you invite somebody to a topic, Discourse creates:

    • Event notifications for “Invite”: For the user you invited. For the e-mail created by this event notification, the same restrictions as for the “quoted” event apply, see above.
  5. When you edit the content of a post: If the post is your own, no notifications whatsoever are created. Otherwise, it does not matter if this post is wiki or not, or if it is the first post of a topic or not. Discourse creates the following notifications:

    • Event notifications for “Edit”: For the author of the post. Note that wiki posts are not treated specially: only the user shown in the avatar icon is considered the author of the post who will be notified about likes. For the e-mail created by this event notification, the same restrictions as for the “quoted” event apply, see above.

    • Event notifications for “quoted”: (For details, see above for the same event.) [TODO: Find out if this notification is created at all when editing post – we haven’t see it in practice so far.]

    • Event notifications for “linked”: For the author of the post you linked to, if any. This notification will be shown on-platform, not by e-mail. [TODO: Find out if this notification is created at all when editing post – we haven’t see it in practice so far.]

    • Event notifications for “@mention”: For anyone @mentioned in the new version of the post and has not set the subscription for the topic, category or tag to “Muted”. The on-platform notification will appear to come from the editing user, which is confusing where this is not the original author of the post. (For more details, see above for the same event, and about auto-tracking of topics in muted categories and tags as documented for “quoted” events above.) [TODO: Find out if and how user muting influences this notification.]

  6. When you change the category of a topic, Discourse creates:

    • Content notifications: For users who subscribed to the topic’s new category with level “Watching First Post” or higher, and have not read the topic before. However, if you add the tag with the admin bulk actions feature, no content notification is created.

    • Event notifications for “new topic”: For the same users who got the content notifications already. [TODO: Confirm that this really happens. Maybe not, because the topic is not exactly “new”.]

  7. When you add a tag to a topic, Discourse creates:

    • Content notifications: For users who subscribed to the tags that you added to the topic, with level “Watching” or higher, and have not read the topic before. However, if you add the tag with the admin bulk actions feature, no content notification is created.

    • Event notifications for “new topic”: For the same users who got the content notifications already. [TODO: Confirm that this really happens. Maybe not, because the topic is not exactly “new”.]

  8. When you send somebody a private message, Discourse creates:

    • Event notifications for “private message”: For the recipient(s) of the message. This notification will be shown on-platform, and possibly by e-mail. The latter depends on the user setting “user menu → Preferences → Email → Send me an email when someone messages me …”. It is enabled by default.

5.3. Where and when does Discourse show content notifications?

If the event-triggering user is muted by the recipient (under “Account Menu → Preferences → Notifications → Users: Muted”) or if the content is muted by the recipient, the notification event is not shown anywhere. Else, it is always shown as on-platform, and maybe by e-mail, as governed by the highest notification level found among the user’s settings for the topic, category and applied tags.

An e-mail is however not sent immediately. If the target user is active on the platform (“clicks any link or button”) after the on-platform notification was created, no e-mail is sent because the platform assumes that the user already saw the blue notification bubble (even if not opening the menu and clicking on the notification). The platform will wait for a minimum of 10 minutes for such activity (see in “user menu → Preferences → Email”: “We’ll only email you if we haven’t seen you in the last 10 minutes.”). This is the default behavior, but the user can also configure Discourse to send e-mails even when she is active on the platform.

In addition, the platform will wait longer than 10 minutes before sending an e-mail, as required to give users a chance to finalize their content first by re-editing it after posting. Currently, this is 10 minutes for normal content, so no additional wait time over the default 10 minutes from “waiting for user activity” (see config parameter “email time window mins”). It is however 20 minutes for private messages (see config parameter “private email time window mins”). [TODO: Confirm if that latter config parameter indeed refers to private messages, or to posts in protected categories.]

In addition, the platform might wait even longer before sending an e-mail, depending on the user’s subscription level for the concerned content. Subscription levels have the following effects:

  • Notification level “Muted”: The notification is not shown on-platform, and also not by e-mail.

  • Notification level “Normal:” The notification is not shown on-platform, and also not by e-mail. The user can still get a notification for quotes, a direct reply or an @mention, but this is covered under “Event notifications” below.

  • Notification level “Tracking”: “New” counter for a new topic in a tracked category / with a tracked tag, “Unread” counter for every new reply in a tracked topic. These are entries in the user’s “New” resp. “Unread” tabs on the platform. Note that entries in the “New” tab will disappear automatically again as governed by the user’s setting “user menu → Preferences → Notifications→ Consider topics new when:”.

    If the content results in a current entry in the “Unread” or “New” tab, an e-mail is sent for that content if the user has enabled the setting “When I don’t visit here, send me an email summary of popular topics and replies”. These e-mails are aggregated into activity summary e-mails (“digests”) according to the maximum frequency configured by the user. [TODO: Find out the default value for that setting and the associated frequency setting.] In addition, there is a user setting that lets users exclude “New” tab content from new users in e-mails, as they are spammers with some likelyhood (see user setting “Include content from new users in summary emails”). [TODO: Document what the default value for that setting is.]

  • Notification level “Watching”: Like “Tracking”, but e-mails are sent immediately. So they are not included into the next digest / activity summary.

5.4. Where and when does Discourse show event notifications?

Not at all from blocked users. If the event-triggering user is muted by the recipient (under “Account Menu → Preferences → Notifications → Users: Muted”), the notification event is not shown anywhere.

As user menu and desktop notifications. By default, the notification is always shown as in the user menu and (if the user enabled them) as a desktop notification. [TODO: not sure about this, to be checked]. Event notifications do not influence the “New” and “Unread” counters.

As e-mail. Depending on the triggering event and the user’s settings for such an event, it will also be sent as an e-mail. See the list of triggering events above for the details.

Anyway, an e-mail is not sent immediately: if the target user is active on the platform for a certain time window after the on-platform notification was created, no e-mail is sent. The default time window is 10 minutes but users can change this in “user menu → Preferences → Email”: “We’ll only email you if we haven’t seen you in the last 10 minutes.” In addition, a user can also change this default behavior in the user settings to send e-mails even when she is active on the platform.

6. Other aspects

6.1. How to work with the Discourse API?

We supply the standard public and access protected Discourse APIs, and also our own extensions to the access protected Discourse API that allow access to ethical consent data and to OpenEthnograper codes and annotations.

All the details are documented here:

6.2. How to create a custom Discourse theme?

This is treated in its own topic here:

6.3. Staff

Staff members are official representatives of this community. There are two kinds of Staff:

  1. Admins, who can do anything and configure anything on this site.
  2. Moderators, who can edit all posts and users, but cannot add categories or change any site settings.

Staff members can exercise their admin superpowers any time via the admin dashboard at /admin. You can also access it via the “hamburger” menu in the upper right. Admin functions are generally marked with the wrench :wrench: icon, so look for that.

To add additional staff members:

6.4. Social Logins

Users can log in with traditional local username and password accounts. You may want to add:

You can also set up single-sign on, or even build your own login method.

6.5. Test Your Email

Email is required for new account signups and notifications. Test your email to make sure it is configured correctly! Visit the admin email settings, then enter an email address in the “email address to test” field and click send test email.

  • You got the test email? Great! Read that email closely, it has important email deliverability tips.

  • You didn’t get the test email? This means your users probably aren’t getting any signup or notification emails either.

  • Email deliverability can be hard. Read Email Service Configuration.

If you’d like to enable replying to topics via email, see this howto.

6.6. Categories

You have three default categories:

  1. Site Feedback – general discussion about the site itself. It’s important!

  2. Lounge – a perk for users at trust level 3 and higher

  3. Staff – visible only to staff (admins and moderators)

Don’t create too many initial categories, as you can overwhelm your audience. You can always add more categories, and easily bulk recategorize topics later. It’s better to figure out the organization as you go rather than assuming you’ll get it all right from the beginning (hint: you won’t).

To add a category, visit the categories page, then click Create Category at the upper right. You can set security per-category so only certain groups of users can see topics in that category.

Every category has an initial “About this category” topic. This topic will be pinned to the top of the category, and the description you enter will be used in a bunch of places. Be sure to give your new category a good, clear description, so people understand what belongs there!

6.7. Pinned Topics and Banners

Note that pinning topics does work a little differently in Discourse:

  • Once someone reads to the bottom of a pinned topic, it is automatically unpinned for them specifically. They can change this via the personal pin controls at the bottom of the topic.

  • When staff pins a topic, they can pin it globally to all topic lists, or just within its category.

If a pin isn’t visible enough, you can also turn one single topic into a banner. The banner topic floats on top of all topics and all primary pages. Users can permanently dismiss this floating banner by clicking the × in the upper right corner.

To make (or remove) a pin or a banner, use the admin wrench at the top right or bottom of the topic.

6.8. New User Sandbox and the Trust System

If your discussion area is be open to the public, new visitors will arrive that are initially strangers to the community. Discourse has a trust system where users can, over time, earn the trust of the community and gain abilities to assist in governing their community.

Discourse is designed to offer safe defaults for public communities, even with no active moderation.

> 0 (new) → 1 (basic) → 2 (member) → 3 (regular) → 4 (leader)

All new users start out in a sandbox with restrictions for everyone’s safety. Trust level 0 (new) users cannot

  • post more than 2 hyperlinks

  • post any images or file attachments

  • send private messages

  • flag posts or topics

  • have actual links in the “about me” field of their profile

  • @name mention more than 2 users in a post

Every action a user can take is rate limited for safety, and especially so for new users. But don’t worry, new users can transition to trust level 1 in about 10 minutes of reading.

These defaults are safe, but note that while in “bootstrap mode” after you set up your site, all new users will be granted trust level 1 until you reach 50 users.

6.9. Sending Invitations

One way to get people to visit your site is to invite them via email. You can do this via:

  • The Invite button at the bottom of the topic.

  • The Invite area on your profile page.

The invite area on your profile page also includes advanced Staff methods of sending bulk invites, and inviting users into groups.

6.10. Maintenance

6.11. Need more Help?

For more assistance on configuring and running your Discourse forum, see meta.discourse.org. In particular, documentation is kept there in the howto category, and especially relevant howtos from there include:


Edgeryders Community Building Workshop in Rijeka, November 2018
Guide for community managers
Participio Development Lab
Adding a table of contents
Using the edgeryders.eu APIs
Trust in Play - The Federated Discourse site
About the Autarky Lab category
Creating an access restricted category
:green_book: Open Ethnographer Manual
:green_book: Discourse User Manual for edgeryders.eu
:green_book: Edgeryders Communities Platform Manual
Welcoming new members