wassname/talk
1
0
Fork 0
mirror of https://github.com/wassname/talk.git synced 2026-07-07 12:01:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #1098 from coralproject/talk-product-guide-features

Browse Source 
Talk Product Guide - features and configuration
This commit is contained in:
Kim Gardner
2017-10-23 19:41:58 +01:00
committed by GitHub
parent e1f897ec17 9fc0fc37db
commit fb9419f2ad
15 changed files with 616 additions and 95 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/_data/nav.yaml
+10
View File
@@ -17,10 +17,16 @@ items:
children:
- title: How Talk Works
url: /how-talk-works/
- title: Commenter Features
url: /commenter-features/
- title: Moderator Features
url: /moderator-features/
- title: Trust
url: /trust/
- title: Toxic Comments
url: /toxic-comments/
- title: Configuring Talk
url: /configuring-talk/
- title: Plugins
children:
- title: Plugins Overview
@@ -31,3 +37,7 @@ items:
url: /additional-plugins/
- title: Plugin Recipes
url: /plugin-recipes/
- title: FAQ
children:
- title: FAQ
url: /faq/
docs/_docs/02-01-required-configuration.md
+6 -6
View File
@@ -19,7 +19,7 @@ If you've already configured your application with the required configuration,
you can further customize it's behavior by applying
[Advanced Configuration]({{ "/advanced-configuration/" | relative_url }}).
### TALK_MONGO_URL
## TALK_MONGO_URL
The database connection string for the MongoDB database. This usually takes the
form of:
@@ -31,7 +31,7 @@ TALK_MONGO_URL=mongodb://<DATABASE USER>:<DATABASE PASSWORD>@<DATABASE HOST>:<DA
Refer to [connection string uri format](https://docs.mongodb.com/manual/reference/connection-string/){:target="_blank"}
for the detailed url scheme of the MongoDB url.
### TALK_REDIS_URL
## TALK_REDIS_URL
The database connection string for the Redis database. This usually takes the
form of:
@@ -50,7 +50,7 @@ TALK_REDIS_URL=redis://127.0.0.1:6379/2
Refer to [uri scheme](http://www.iana.org/assignments/uri-schemes/prov/redis){:target="_blank"}
for the detailed url scheme of the Redis url.
### TALK_ROOT_URL
## TALK_ROOT_URL
The root url of the installed application externally available in the format:
@@ -70,7 +70,7 @@ TALK_ROOT_URL=https://talk.coralproject.net/
_Note that we omitted the `PORT`, as it was implied by setting the `SCHEME` to
`https`._
### TALK_JWT_SECRET
## TALK_JWT_SECRET
Used to specify the application signing secret. You can specify this using a
simple string, we recommend using a password generator and pasting it's output.
@@ -85,7 +85,7 @@ Be default, we sign our tokens with HMAC using a SHA-256 hash algorithm. If you
want to change the signing algorithm, or use multiple signing/verifying keys,
refer to our [Advanced Configuration]({{ "/advanced-configuration/" | relative_url }}) documentation.
### TALK_FACEBOOK_APP_ID
## TALK_FACEBOOK_APP_ID
The Facebook App ID for your Facebook Login enabled app. You can learn more
about getting a Facebook App ID at the
@@ -95,7 +95,7 @@ or by visiting the
guide. This is only required while the `talk-plugin-facebook-auth` plugin is
enabled.
### TALK_FACEBOOK_APP_SECRET
## TALK_FACEBOOK_APP_SECRET
The Facebook App Secret for your Facebook Login enabled app. You can learn more
about getting a Facebook App Secret at the
docs/_docs/02-02-advanced-configuration.md
+41 -41
View File
@@ -19,37 +19,37 @@ If this is your first time configuring Talk, ensure you've also added the
[Required Configuration]({{ "/configuration/" | relative_url }}) as well,
otherwise the application will fail to start.
### TALK_CACHE_EXPIRY_COMMENT_COUNT
## TALK_CACHE_EXPIRY_COMMENT_COUNT
Configure the duration for which comment counts are cached for, parsed by
[ms](https://www.npmjs.com/package/ms){:target="_blank"}. (Default `1hr`)
### TALK_DEFAULT_LANG
## TALK_DEFAULT_LANG
Specify the default translation language. (Default `en`)
### TALK_DEFAULT_STREAM_TAB
## TALK_DEFAULT_STREAM_TAB
Specify the default stream tab in the admin. (Default `all`)
### TALK_DISABLE_AUTOFLAG_SUSPECT_WORDS
## TALK_DISABLE_AUTOFLAG_SUSPECT_WORDS
When `TRUE`, disables flagging of comments that match the suspect word filter. (Default `FALSE`)
### TALK_DISABLE_EMBED_POLYFILL
## TALK_DISABLE_EMBED_POLYFILL
When set to `TRUE`, the build process will not include the
[babel-polyfill](https://babeljs.io/docs/usage/polyfill/){:target="_blank"}
in the embed.js target that is loaded on the page that loads the embed. (Default
`FALSE`)
### TALK_DISABLE_STATIC_SERVER
## TALK_DISABLE_STATIC_SERVER
When `TRUE`, it will not mount the static asset serving routes on the router.
This is used primarily in conjunction with [TALK_STATIC_URI](#talk_static_uri){: .param}
when the static assets are being hosted on an external domain. (Default `FALSE`)
### TALK_HELMET_CONFIGURATION
## TALK_HELMET_CONFIGURATION
A JSON string representing the configuration passed to the
[helmet](https://github.com/helmetjs/helmet){:target="_blank"} middleware. It
@@ -68,20 +68,20 @@ TALK_HELMET_CONFIGURATION={"hsts": false}
To disable these headers from being sent.
### TALK_INSTALL_LOCK
## TALK_INSTALL_LOCK
When `TRUE`, disables the dynamic setup endpoint `/admin/install` from even
loading. This prevents hits to the database with enabled. This should always be
set to `TRUE` after you've deployed Talk. (Default `FALSE`)
### TALK_JWT_ALG
## TALK_JWT_ALG
The algorithm used to sign/verify JWT’s used for session management. Read up
about alternative algorithms on the
[jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken#algorithms-supported){:target="_blank"}
package. (Default `HS256`)
#### Shared Secret
### Shared Secret
{:.no_toc}
You would use a shared secret when you have no need to share the tokens with
@@ -102,7 +102,7 @@ These must be provided in the form:
```
{: .no-copy}
#### Asymmetric Secret
### Asymmetric Secret
{:.no_toc}
You would use a asymmetric secret when you want to share the token in your
@@ -138,23 +138,23 @@ certificates that match our required format: [coralcert](https://github.com/cora
This tool can generate RSA and ECDSA certificates, check it's [README](https://github.com/coralproject/coralcert){:target="_blank"}
for more details.
### TALK_JWT_AUDIENCE
## TALK_JWT_AUDIENCE
The audience [aud](https://tools.ietf.org/html/rfc7519#section-4.1.3){:target="_blank"}
claim for login JWT tokens. (Default `talk`)
### TALK_JWT_CLEAR_COOKIE_LOGOUT
## TALK_JWT_CLEAR_COOKIE_LOGOUT
When `FALSE`, Talk will not clear the cookie with name
[TALK_JWT_SIGNING_COOKIE_NAME](#talk_jwt_signing_cookie_name){: .param} when logging out
but will still blacklist the token. (Default `TRUE`)
### TALK_JWT_COOKIE_NAME
## TALK_JWT_COOKIE_NAME
The default cookie name to check for a valid JWT token to use for verifying a
user. (Default `authorization`)
### TALK_JWT_COOKIE_NAMES
## TALK_JWT_COOKIE_NAMES
The different cookie names to check for a JWT token in, separated by a `,`. By
default, we always use the value of [TALK_JWT_COOKIE_NAME](#talk_jwt_cookie_name){: .param}
@@ -176,19 +176,19 @@ Would mean we would check the following cookies (in order) for a valid token:
2. `coralproject.talk`
3. `coralproject.auth`
### TALK_JWT_DISABLE_AUDIENCE
## TALK_JWT_DISABLE_AUDIENCE
When `TRUE`, Talk will not verify or sign JWT’s with an audience
[aud](https://tools.ietf.org/html/rfc7519#section-4.1.3){:target="_blank"}
claim, even if [TALK_JWT_AUDIENCE](#talk_jwt_audience){: .param} is set. (Default `FALSE`)
### TALK_JWT_DISABLE_ISSUER
## TALK_JWT_DISABLE_ISSUER
When `TRUE`, Talk will not verify or sign JWT’s with an issuer
[iss](https://tools.ietf.org/html/rfc7519#section-4.1.1){:target="_blank"}
claim, even if [TALK_JWT_ISSUER](#talk_jwt_issuer){: .param} is set. (Default `FALSE`)
### TALK_JWT_EXPIRY
## TALK_JWT_EXPIRY
The expiry duration [exp](https://tools.ietf.org/html/rfc7519#section-4.1.4){:target="_blank"}
for the tokens issued for logged in sessions, parsed by
@@ -199,12 +199,12 @@ If the user logs out, then an entry is created in the token blacklist of it's
set to be automatically removed at it's expiry time. It is important for this
reason to create reasonable expiry lengths as to minimize the storage overhead.
### TALK_JWT_ISSUER
## TALK_JWT_ISSUER
The issuer [iss](https://tools.ietf.org/html/rfc7519#section-4.1.1){:target="_blank"}
claim for login JWT tokens. (Defaults to value of [TALK_ROOT_URL]({{ "/configuration/#talk_root_url" | relative_url }}){: .param})
### TALK_JWT_SECRET
## TALK_JWT_SECRET
Used to specify the application signing secret. You can specify this using a
simple string, we recommend using a password generator and pasting it's output.
@@ -225,7 +225,7 @@ Refer to the documentation for [TALK_JWT_ALG](#talk_jwt_alg){: .param} for other
methods and other forms of the `TALK_JWT_SECRET`. If you are interested in using
multiple keys, then refer to [TALK_JWT_SECRETS](#talk_jwt_secrets){: .param}.
### TALK_JWT_SECRETS
## TALK_JWT_SECRETS
Used when specifying multiple secrets used for key rotations. This is a JSON
encoded array, where each element matches the JWT Secret pattern. When this is
@@ -261,12 +261,12 @@ Refer to the documentation on the [TALK_JWT_ALG](#talk_jwt_alg){: .param} for mo
information on what to store in these parameters.
{: .code-aside}
### TALK_JWT_SIGNING_COOKIE_NAME
## TALK_JWT_SIGNING_COOKIE_NAME
The default cookie name that is use to set a cookie containing a JWT that was
issued by Talk. (Defaults to value of [TALK_JWT_COOKIE_NAME](#talk_jwt_cookie_name){: .param})
### TALK_JWT_USER_ID_CLAIM
## TALK_JWT_USER_ID_CLAIM
Specify the claim using dot notation for where the user id should be stored/read
to/from. (Default `sub`)
@@ -287,13 +287,13 @@ Then we would set `TALK_JWT_USER_ID_CLAIM` to:
TALK_JWT_USER_ID_CLAIM=user.id
```
### TALK_KEEP_ALIVE
## TALK_KEEP_ALIVE
The keepalive timeout that should be used to send keep alive messages through
the websocket to keep the socket alive, parsed by
[ms](https://www.npmjs.com/package/ms){:target="_blank"}. (Default `30s`)
### TALK_RECAPTCHA_PUBLIC
## TALK_RECAPTCHA_PUBLIC
Client secret used for enabling reCAPTCHA powered logins. If
[TALK_RECAPTCHA_SECRET](#talk_recaptcha_secret){: .param} and
@@ -302,7 +302,7 @@ default to providing only a time based lockout. Refer to
[reCAPTCHA](https://www.google.com/recaptcha/intro/index.html) for information
on getting an account setup.
### TALK_RECAPTCHA_SECRET
## TALK_RECAPTCHA_SECRET
Server secret used for enabling reCAPTCHA powered logins. If
[TALK_RECAPTCHA_SECRET](#talk_recaptcha_secret){: .param} and
@@ -311,7 +311,7 @@ default to providing only a time based lockout. Refer to
[reCAPTCHA](https://www.google.com/recaptcha/intro/index.html) for information
on getting an account setup.
### TALK_REDIS_CLIENT_CONFIG
## TALK_REDIS_CLIENT_CONFIG
Configuration overrides for the redis client configuration in a JSON encoded
string. Configuration is overridden as the second parameter to the redis client
@@ -319,30 +319,30 @@ constructor, and is merged with default configuration. Refer to the
[ioredis](https://github.com/luin/ioredis){:target="_blank"} docs on the
available options. (Default `{}`)
### TALK_REDIS_CLUSTER_CONFIGURATION
## TALK_REDIS_CLUSTER_CONFIGURATION
The JSON encoded form of the cluster nodes. Only required when
[TALK_REDIS_CLUSTER_MODE](#talk_redis_cluster_mode){: .param} is `CLUSTER`. See
[https://github.com/luin/ioredis#cluster](https://github.com/luin/ioredis#cluster){:target="_blank"}
for configuration details. (Default `[]`)
### TALK_REDIS_CLUSTER_MODE
## TALK_REDIS_CLUSTER_MODE
The cluster mode of the redis client. Can be either `NONE` or `CLUSTER`.
(Default `NONE`)
### TALK_REDIS_RECONNECTION_BACKOFF_FACTOR
## TALK_REDIS_RECONNECTION_BACKOFF_FACTOR
The time factor that will be multiplied against the current attempt count
between attempts to connect to redis, parsed by
[ms](https://www.npmjs.com/package/ms){:target="_blank"}. (Default `500 ms`)
### TALK_REDIS_RECONNECTION_BACKOFF_MINIMUM_TIME
## TALK_REDIS_RECONNECTION_BACKOFF_MINIMUM_TIME
The minimum time used to delay before attempting to reconnect to redis, parsed
by [ms](https://www.npmjs.com/package/ms){:target="_blank"}. (Default `1 sec`)
### TALK_ROOT_URL_MOUNT_PATH
## TALK_ROOT_URL_MOUNT_PATH
When set to `TRUE`, the routes will be mounted onto the `<PATHNAME>` component
of the [TALK_ROOT_URL]({{ "/configuration/#talk_root_url" | relative_url }}){: .param}.
@@ -361,7 +361,7 @@ Then all the routes for the API will be expecting to be hit on `/talk/`, such as
can perform the path stripping when serving an upstream proxy, but some CDN's
cannot. You would use this option in the latter situation.
### TALK_SMTP_EMAIL
## TALK_SMTP_EMAIL
The email address to send emails from using the SMTP provider in the format:
@@ -371,23 +371,23 @@ TALK_SMTP_EMAIL="The Coral Project" <support@coralproject.net>
Including the name and email address.
### TALK_SMTP_HOST
## TALK_SMTP_HOST
The domain for the SMTP provider that you are using.
### TALK_SMTP_PASSWORD
## TALK_SMTP_PASSWORD
The password for the SMTP provider you are using.
### TALK_SMTP_PORT
## TALK_SMTP_PORT
The port for the SMTP provider that you are using.
### TALK_SMTP_USERNAME
## TALK_SMTP_USERNAME
The username of the SMTP provider you are using.
### TALK_STATIC_URI
## TALK_STATIC_URI
Used to set the uri where the static assets should be served from. This is used
when you want to upload the static assets through your build process to a
@@ -395,14 +395,14 @@ service like Google Cloud Storage or Amazon S3 and you would then specify the
CDN/Storage url. (Defaults to value of
[TALK_ROOT_URL]({{ "/configuration/#talk_root_url" | relative_url }}){: .param})
### TALK_THREADING_LEVEL
## TALK_THREADING_LEVEL
Specify the maximum depth of the comment thread. (Default `3`)
**Note that a high value for `TALK_THREADING_LEVEL` will result in large
performance impacts.**
### TALK_WEBSOCKET_LIVE_URI
## TALK_WEBSOCKET_LIVE_URI
Used to override the location to connect to the websocket endpoint to
potentially another host. This should be used when you need to route websocket
@@ -419,7 +419,7 @@ is `FALSE`, or the path component of
**Warning: if used without managing the auth state manually, auth
cannot be persisted due to browser restrictions.**
### TRUST_THRESHOLDS
## TRUST_THRESHOLDS
Configure the reliability thresholds for flagging and commenting. (Default
`comment:2,-1;flag:2,-1`)
docs/_docs/04-01-product-guide-how-talk-works.md → docs/_docs/03-01-product-guide-how-talk-works.md
View File
docs/_docs/03-02-product-guide-commenter-features.md
+200
View File
@@ -0,0 +1,200 @@
---
title: Commenter Features
permalink: /commenter-features/
---
## Signing up for Talk
There are 2 ways that newsrooms can support signup/login functionality with Talk:
*Use Talk’s auth plugin out of the box (supports account registration with username and password, as well as features like forgot password)
*Create their own auth plugin to integrate with your own auth systems
We also provide a Facebook auth plugin that supports logging in with Facebook (you must provide your own Facebook App ID and Secret, which you can read more about here: [https://developers.facebook.com](https://developers.facebook.com){:target="_blank"})
## Comments and Replies
Talk supports a standard comment hierarchy. There are top-level (or parent) comments, and then replies to that comment (or children comments).
### Permalinks
All levels of comments and replies are able to be linked to via permalink. Permalinks are structured using a `commentId` query param:
```text
https://<your asset url>?commentId=<the comment id>
```
{:.no-copy}
### Threading
Talk supports by default 3 levels of threading, meaning each top-level comment
has a depth of 3 replies; replies beyond that are not nested below the 3rd
level. You can adjust this using the
[TALK_THREADING_LEVEL]({{ "/advanced-configuration/#talk_threading_level" | relative_url }}){:.param}
configuration variable. We don’t recommend deep threading because it can cause
issues with styling, especially on mobile.
You can style threaded comments using these CSS classes:
```
talk-stream-comment-wrapper-level-${depth}
talk-stream-comment
talk-stream-comment-level-${depth}
talk-stream-highlighted-comment
talk-stream-pending-comment
```
{:.no-copy}
### Automatic Updates
Talk supports real-time loading and updating of comments, via subscriptions
(specifically GraphQL Subscriptions); this enables us to not have to refresh to
see new comments on a given comment stream.
Talk enables this via “Load More” buttons for both top-level comments (this
button appears at the top of the stream), and within conversation threads (this
button appears in situ for replies).
We’ve decided to go this route in order to make the viewing experience as smooth
as possible, so that the feed of comments doesn’t change as you’re reading just
because new comments are coming in. This could be especially disruptive on
breaking news and/or controversial stories with very active discussions.
### Comment Character Limits
You can enable Talk to limit the character length for comments, for example,
some newsrooms we’ve worked with prefer a limit between 2000 and 5000
characters. Commenters will be alerted that they have gone over that number and
won’t be able to submit their comment until they’ve edited it. This can be a
useful tool to ensure commenters are concise with their comments.
## Comment Reactions
Talk comes with a `respect` button out of the box. Why a “respect” button, you
ask?
[Read more here](https://mediaengagement.org/research/engagement-buttons/){:target="_blank"}.
We also have 2 more plugins, `like` and `love`, that you can turn on and
experiment with on your own Talk install.
And our plugin architecture makes it easy to create your own custom reaction
buttons too.
## Reporting Comments
Readers can report comments if they feel they’re unsuitable. They can choose one
of the following reasons:
* This comment is offensive
* This looks like an ad/marketing
* I don’t agree with this comment
* Other
They can also include more information and this shows for moderators in the Flag
Detail area on the comments in the moderation queues.
Comments that are reported go to the Reported queue, with the exception of “I
don’t agree with this comment”. This option is a useful way to let other readers
vent their frustration, but since just disagreeing with something doesn’t mean
it’s not suitable, we leave it be.
## Reporting Usernames
Usernames can also be reported by readers, if the username is inappropriate or
offensive. They can choose one of the following reasons:
* This username is offensive
* I don't like this username
* This user is impersonating
* This looks like an ad/marketing
Reported usernames go to the Reported Usernames queue which is located in the
Community tab. If a username is rejected by a moderator, the commenter is
prompted to change their username and they are suspended from commenting,
replying or reacting to comments until they do so. They receive an email, and
also a message at the top of their comment streams that let’s them know they’re
suspended.
If the commenter changes their username, it goes back to the Reported Usernames
queue for approval. If the updated username is accepted by a moderator, the
commenter is no longer suspended and continue interacting with the community. If
the username is rejected, the commenter remains suspended until they change
their username to something appropriate.
Approved usernames that are reported do not show up in the Reported Usernames
queues any longer, since they have been specifically OK’ed by a moderator.
## Ignoring Users
Commenters can ignore other commenters and essentially mute them entirely from
the comment platform. Commenters can manage their ignored users list in their My
Profile tab.
## Featured Comments
Moderators can feature comments that they want to highlight and recommend to
their community. Featured comments show up on a separate tab, that is the
default for the comment stream. Featured comments within the stream show a
Featured badge.
## Sorting the Stream
Readers can sort the stream in 4 ways based on their viewing preferences:
* Oldest first
* Newest first
* Most respect first (or most liked, most loved, etc., depending on what
reactions you use)
* Most replied first
We also make it easy to add more sorts via custom plugins.
## Badges
Badges differentiate users and comments on the stream. By default, Talk has two
badges.
The Staff user badge that shows when a commenter has an Admin, Moderator, or
Staff role.
The Featured comment badge shows when a comment has been featured.
Another optional badge is the Subscriber badge (which is available as a
[Recipe]({{ "/plugin-recipes/#recipe-subscriber" | relative_url}}).
Badges are another easy part of Talk to customize by creating a new `tag`, then
setting some rules for when it should show, and how the badge should be styled.
## My Profile
The My Profile tab is where commenters can go to see their comment history, as
well as reactions and replies to their comments. They can also see their email
address associated with Talk, and manage their Ignored Users list here.
## Notifications & Error Messaging
Talk leverages notification and messages on the stream to alert users to
important information about their comment or their account.
### Pre-moderation of comments
If a stream is set to Pre-mod, or a commenter’s Trust karma score has fallen to
negative, or if for any other reason their comment is being pre-moderated, they
will get a notification letting them know this when they post a comment.
### Suspension because of Username
When a commenter has been suspended because their username is inappropriate,
they will see a message at the top of their streams stating this.
### Timed Suspension
When a commenter has been suspended for a block of time (aka a “time-out”), they
will see a message at the top of their streams stating this.
### Ban
When a commenter has been banned, they will see a message at the top of their
streams staging this.
docs/_docs/03-03-product-guide-moderator-features.md
+188
View File
@@ -0,0 +1,188 @@
---
title: Moderator Features
permalink: /moderator-features/
---
## The Talk Admin
The Admin is your moderators will moderate your comments, and your Admins will
configure and manage the different parts of Talk.
### Dashboard
The Dashboard provides real-time information to moderators so they know at a
glance where they should direct their attention. It shows what articles are
receiving the most reports and where the most active conversations are
happening.
### Moderate
This is the tab where Moderators will spend the majority of their time. They can
choose (via the dropdown) which story they would like to moderate, or moderate
site-wide.
#### Default Mod Queues
**New**
The New queue contains all comments that have not been moderated yet.
**Reported**
The Reported queue contains all comments that need moderator attention.
**Approved**
The Approved queue contains all approved comments.
**Rejected**
The Rejected queue contains all comments that have been rejected, either
manually by moderators or automatically, e.g. they have used a banned word.
**All**
The All queue contains all comments that have been submitted either article or
site-wide.
#### Moderation Badges
**Pre-mod**
The Pre-mod badge signifies comments that are being pre-modded.
**User**
The User badge signifies comments that have been reported by another user.
**History**
The History badge signifies comments that have been flagged because of a user’s
history.
**Toxic**
The Toxic badge signifies comments that are above the set Toxicity Probability
Threshold. Note you must have [talk-plugin-toxic-comments]({{ "/additional-plugins/#talk-plugin-toxic-comments" | relative_url }}){:.param} enabled.
[Read more about Toxic Comments here]({{ "/toxic-comments/" | relative_url}}).
**Suspect**
The Suspect badge signifies comments that contain a Suspect Word.
**Contains Link**
The Contains Link badge signifies a comment that contains a link, which can
sometimes mean it is a spam or ad comment.
**Flag Details View**
At the bottom of each comment in the moderation queues, you can see more
information about a comment’s flags by clicking on More Detail.
#### Moderator Actions
**Accept**
Accepting a comment ensures that the comment is displayed on the stream.
**Reject**
Rejecting a comment removes the comment from the stream.
**Feature**
Featuring a comment adds that comment to the Featured Comments tab on the
stream.
**Suspend User**
Suspending a user allows a moderator to give a commenter a “time-out”; during
that time they won’t be allowed to post comments or react to comments.
**Ban User**
Banning a user allows a moderator to permanently disallow a commenter to
interact with their community. The commenters previous comments will remain on
the site. This action can only be un-done manually by a moderator.
#### Viewing a User’s Comment History
In order to get an idea of what sort of a commenter someone is, moderators can
click on the commenters username in any moderation queue and see details about
their history.
**Username, Email and Member Since Date**
This shows the basic details about a commenter.
**Total Comments**
This shows the number of comments that a commenter has made that currently
display on the site.
**Reject Rate**
This shows the % of comments a commenter has had rejected by moderators, or
automatically.
**Reports**
This shows if a commenter is a reliable flagger, an unreliable flagger, or a
neutral flagger. [Read more about reliable and unreliable flaggers here]({{"/trust/#reliable-and-unreliable-flaggers" | relative_url }}).
**Moderating from this View**
Talk also allows you to moderate a commenters recent comments from this view.
#### Keyboard Shortcuts
Talk also supports a number of keyboard shortcuts that moderators can leverage
to moderate quickly:
| Shortcut | Action |
| -------- | ------------------------------- |
| `j` | Go to the next comment |
| `k` | Go to the previous comment |
| `ctrl+f` | Open search |
| `t` | Switch queues |
| `s` | Toggle single comment edit view |
| `?` | Open this menu |
| `d` | Approve |
| `f` | Reject |
### Stories
In the Stories tab moderators can view all the stories that have Talk comments
embedded on them, as well as be able to Open or Close comment streams on
stories.
### Community
The Community tab houses everything having to do with your team and your
commenters.
#### Moderating Usernames
Any usernames that have been reported will show in the Reported Usernames
sub-tab. Moderators can approve usernames if they’re suitable, or reject a
username. If a username is rejected, the commenter will be notified that they
need to change their username; until they do, they will be suspended from Talk.
The updated username then again appears in this queue for a decision by
moderators.
#### Managing People & Roles
All your team and commenters show in the People sub-tab. From here, you can
manage your team members’ roles (Admins, Moderators, Staff), as well as search
for commenters and take action on them (e.g. Ban/Un-ban, Suspend, etc.). ###
Configure
See [Configuring Talk]({{ "/configuring-talk/" | relative_url }}).
## Moderating via the Comment Stream
Moderators can also choose to moderate comments in situ. If you are logged in as
a Moderator or Admin, you will see a caret dropdown on each comment that allows
you to Approve, Reject, or Feature comments, or Ban a User directly from the
comment stream.
docs/_docs/04-02-product-guide-trust.md → docs/_docs/03-04-product-guide-trust.md
+2 -2
View File
@@ -6,7 +6,7 @@ permalink: /trust/
Trust is a set of components within Talk that incorporate automated moderation
features based on a user's previous behavior.
### User Karma Score
## User Karma Score
Using Trust’s calculations, Talk will automatically pre-moderate comments of
users who have a negative karma score. All users start out with a `0` neutral
@@ -32,7 +32,7 @@ You can configure your own Trust thresholds by using [TRUST_THRESHOLD]({{"/advan
configuration.
### Reliable and Unreliable Flaggers
## Reliable and Unreliable Flaggers
Trust also calculates how reliable users are in terms of the comments they
report. This information is displayed to moderators in the User History drawer,
docs/_docs/04-03-product-guide-toxic-comments.md → docs/_docs/03-05-product-guide-toxic-comments.md
+3 -3
View File
@@ -21,7 +21,7 @@ Talk (0.8 or 80% is the default), which works like this:
Read more about Coral’s take on toxicity
[on our blog](https://blog.coralproject.net/toxic-avenging/){:target="_blank"}.
### What is the Perspective API?
## What is the Perspective API?
The likely toxicity of a comment is evaluated using scores generated from
[Perspective API](http://perspectiveapi.com/){:target="_blank"}. This is part of
@@ -48,12 +48,12 @@ We’ve talked with their team on several occasions, and have been impressed by
their dedication and commitment to this issue. These are smart people who are
trying to improve a broken part of the internet.
### How do I add the Toxic Comments plugin?
## How do I add the Toxic Comments plugin?
To enable this behavior, visit the
[talk-plugin-toxic-comments]({{ "/additional-plugins/#talk-plugin-toxic-comments" | relative_url }})
plugin documentation.
### Request an API Key
## Request an API Key
You can read more about Google's Perspective API and/or request an API key here: [http://perspectiveapi.com/](http://perspectiveapi.com/).
docs/_docs/03-06-product-guide-configuring-talk.md
+101
View File
@@ -0,0 +1,101 @@
---
title: Configuring Talk
permalink: /configuring-talk/
---
## Configuring an Individual Stream
There are two ways Admins can configure Talk - the first is via the Configure
tab on the comment stream.
### Enable Pre-moderation
Allows toggling pre-moderation for the current comment stream.
### Pre-moderation Comments Containing Links
Allows toggling of pre-moderating comments that have links.
### Ask Readers a Question & Question Icons
Admins can choose to Ask Readers a Question in order to help guide the
discussion. [Read more about why this is important on our blog](https://blog.coralproject.net/the-empty-box/){:target="_blank"}.
There are a selection of icons to display different messaging other than a
question on a particular stream, like an announcement, or general information
about the story.
### Closing a Stream
Closing a stream will prevent new comments. Previous comments will remain
displayed on the stream for readers to view.
## Global Configuration
Global configuration settings are available via Admin > Configure. These
settings are site-wide and will affect all of your comment streams.
### Stream Settings
#### Limit Comment Length
A maximum comment length across the site.
#### Comment Stream Description
Description text that will appear above every comment stream site-wide. We
recommend linking to your Code of Conduct or Community Guidelines. [Read tips on how to write a Code of Conduct here](https://guides.coralproject.net/create-a-code-of-conduct/){:target="_blank"}.
#### Closed Stream Message
A message that will display when streams are closed.
#### Edit Comment Timeframe
The timeframe in seconds in which commenters have to edit their comment.
#### Close Comments After
Default time after which all comment streams will close.
### Moderation Settings
#### Require Email Verification
Require new users to verify their email address prior to commenting.
#### Enable Pre-moderation
Turn on pre-moderation across the site, meaning all comments will need to be
moderated before they will be displayed.
#### Pre-moderate Comments Containing Links
Turn on pre-moderation for comments with links across the site, meaning all
comments with links will need to be moderated before they will be displayed.
#### Banned Words List
A list of words that will trigger a comment to be automatically Rejected.
#### Suspect Words List
A list of words that will trigger a comment to be automatically Reported.
Comments with suspect words will display until a moderator takes action on them.
### Technical Settings
#### Permitted Domains
A list of domains where your Talk instance is allowed to be embedded. Typical
use is `localhost`, `staging.yourdomain.com`, `yourdomain.com`, etc.
#### Embed Script
This is the unique Talk script that is to be used to embed Talk on your website.
#### Custom CSS URL
The link to your custom stylesheet for Talk. This will override any default
styles, so you can make Talk your own!
docs/_docs/03-01-plugins-overview.md → docs/_docs/04-01-plugins-overview.md
View File
docs/_docs/03-02-default-plugins.md → docs/_docs/04-02-default-plugins.md
+19 -21
View File
@@ -16,7 +16,7 @@ Talk that are not enabled by default. You can enable these or disable these
default plugins by consulting the [Plugins Overview]({{ "/plugins/" | relative_url }})
page.
### talk-plugin-auth
## talk-plugin-auth
Source: [plugins/talk-plugin-auth](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-auth){:target="_blank"}
@@ -24,7 +24,7 @@ Enables generic registration via an email address, a username, a password, and a
password confirmation. To sync Talk auth with your own auth systems, you can use
this plugin as a template.
### talk-plugin-facebook-auth
## talk-plugin-facebook-auth
Source: [plugins/talk-plugin-auth](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-auth){:target="_blank"}
@@ -34,12 +34,10 @@ Enables sign-in via Facebook via the server side passport middleware.
Configuration:
{:.no_toc}
- [TALK_FACEBOOK_APP_ID]({{ "/configuration/#talk_facebook_app_id" | relative_url }}){:.param} (**required**) - See the existing documentation for the [TALK_FACEBOOK_APP_ID]({{ "/configuration/#talk_facebook_app_id" | relative_url }}){:.param}.
- [TALK_FACEBOOK_APP_SECRET]({{ "/configuration/#talk_facebook_app_secret" | relative_url }}){:.param} (**required**) - See the existing documentation for the [TALK_FACEBOOK_APP_SECRET]({{ "/configuration/#talk_facebook_app_secret" | relative_url }}){:.param}.
### talk-plugin-featured-comments
## talk-plugin-featured-comments
Source: [plugins/talk-plugin-featured-comments](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-featured-comments){:target="_blank"}
@@ -47,14 +45,14 @@ Enables the ability for Moderators to feature and un-feature comments via the
Stream and the Admin. Featured comments show in a first-place tab on the Stream
if there are any featured comments on that story.
### talk-plugin-respect
## talk-plugin-respect
Source: [plugins/talk-plugin-respect](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-respect){:target="_blank"}
Enables a `respect` reaction button. Why a "respect" button, you ask?
[Read more here](https://mediaengagement.org/research/engagement-buttons/).
### talk-plugin-comment-content
## talk-plugin-comment-content
Source: [plugins/talk-plugin-comment-content](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-comment-content){:target="_blank"}
@@ -62,7 +60,7 @@ Pluginizes the text of a comment to support custom treatment of this text. This
plugin currently parses the given text to see if it contains a link, and makes
them clickable.
### talk-plugin-ignore-user
## talk-plugin-ignore-user
Source: [plugins/talk-plugin-ignore-user](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-ignore-user){:target="_blank"}
@@ -70,20 +68,20 @@ Enables ability for users to ignore (or "mute") other users. If a user is
ignored, you will not see any of their comments. You can un-ignore a user via
the My Profile tab.
### talk-plugin-permalink
## talk-plugin-permalink
Source: [plugins/talk-plugin-permalink](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-permalink){:target="_blank"}
Enables a `Link` button that will provide a permalink to the comment that can be
shared with others.
### talk-plugin-viewing-options
## talk-plugin-viewing-options
Source: [plugins/talk-plugin-viewing-options](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-viewing-options){:target="_blank"}
Pluginizes the sorting/viewing options for a comment stream.
### talk-plugin-sort-newest
## talk-plugin-sort-newest
Source: [plugins/talk-plugin-sort-newest](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-newest){:target="_blank"}
@@ -92,7 +90,7 @@ Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options){:.param}
Provides a sort for the newest comments first. This isn't necessarily required
as the default sort without options/plugins is newest first.
### talk-plugin-sort-oldest
## talk-plugin-sort-oldest
Source: [plugins/talk-plugin-sort-oldest](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-oldest){:target="_blank"}
@@ -100,36 +98,36 @@ Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options){:.param}
Provides a sort for the newest comments first.
### talk-plugin-most-respected
## talk-plugin-sort-most-respected
Source: [plugins/talk-plugin-most-respected](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-most-respected){:target="_blank"}
Source: [plugins/talk-plugin-sort-most-respected](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-most-respected){:target="_blank"}
Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options){:.param}, [talk-plugin-respect](#talk-plugin-respect){:.param}
Provides a sort for the comments with the most `respect` reactions first.
### talk-plugin-most-replied
## talk-plugin-sort-most-replied
Source: [plugins/talk-plugin-most-replied](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-most-replied){:target="_blank"}
Source: [plugins/talk-plugin-sort-most-replied](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-most-replied){:target="_blank"}
Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options){:.param}
Provides a sort for the comments with the most replies first.
### talk-plugin-offtopic
## talk-plugin-offtopic
Source: [plugins/talk-plugin-offtopic](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-offtopic){:target="_blank"}
Allows the comment authors to tag their comment as `Off-Topic` which will add a
visible badge on the frontend to other users that their comment is off-topic.
### talk-plugin-author-menu
## talk-plugin-author-menu
Source: [plugins/talk-plugin-author-menu](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-author-menu){:target="_blank"}
Pluginizes the author's name on hover.
### talk-plugin-member-since
## talk-plugin-member-since
Source: [plugins/talk-plugin-member-since](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-member-since){:target="_blank"}
@@ -137,14 +135,14 @@ Requires: [talk-plugin-author-menu](#talk-plugin-author-menu){:.param}
Displays the date that the user was created as a `Member Since ${created_at}`.
### talk-plugin-moderation-actions
## talk-plugin-moderation-actions
Source: [plugins/talk-plugin-moderation-actions](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-moderation-actions){:target="_blank"}
Enables in-stream moderation so that Moderators can reject, approve comments,
as well as ban users, directly from the comment stream. When [talk-plugin-featured-comments](#talk-plugin-featured-comments){:.param} is enabled
### talk-plugin-flag-details
## talk-plugin-flag-details
Source: [plugins/talk-plugin-flag-details](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-flag-details){:target="_blank"}
docs/_docs/03-03-additional-plugins.md → docs/_docs/04-03-additional-plugins.md
+9 -11
View File
@@ -11,13 +11,13 @@ Talk ships with several plugins that aren't enabled by default:
These plugins can be enabled by consulting the
[Plugins Overview]({{ "/plugins/" | relative_url }}) page.
### talk-plugin-like
## talk-plugin-like
Source: [plugins/talk-plugin-like](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-like){:target="_blank"}
Enables a `like` reaction button.
### talk-plugin-sort-most-liked
## talk-plugin-sort-most-liked
Source: [plugins/talk-plugin-sort-most-liked](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-most-liked){:target="_blank"}
@@ -25,13 +25,13 @@ Requires: [talk-plugin-viewing-options]({{ "/default-plugins/#talk-plugin-viewin
Provides a sort for the comments with the most `like` reactions first.
### talk-plugin-love
## talk-plugin-love
Source: [plugins/talk-plugin-love](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-love){:target="_blank"}
Enables a `love` reaction button.
### talk-plugin-sort-most-loved
## talk-plugin-sort-most-loved
Source: [plugins/talk-plugin-sort-most-loved](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-most-loved){:target="_blank"}
@@ -39,7 +39,7 @@ Requires: [talk-plugin-viewing-options]({{ "/default-plugins/#talk-plugin-viewin
Provides a sort for the comments with the most `love` reactions first.
### talk-plugin-remember-sort
## talk-plugin-remember-sort
Source: [plugins/talk-plugin-remember-sort](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-remember-sort){:target="_blank"}
@@ -47,7 +47,7 @@ Requires: [talk-plugin-viewing-options]({{ "/default-plugins/#talk-plugin-viewin
Enables saving a user’s last sort selection as they browse other articles.
### talk-plugin-deep-reply-count
## talk-plugin-deep-reply-count
Source: [plugins/talk-plugin-deep-reply-count](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-deep-reply-count){:target="_blank"}
@@ -55,7 +55,7 @@ Enables counting of comments to include replies via a new graph edge. Not
recommended for large installations as it will unreasonably reduce the query
efficiency to compute this number.
### talk-plugin-slack-notifications
## talk-plugin-slack-notifications
Source: [plugins/talk-plugin-slack-notifications](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-slack-notifications){:target="_blank"}
@@ -70,12 +70,11 @@ Slack, if this isn't what you want, be sure to use the provided plugin as a
recipe to further customize the behavior*.
Configuration:
{:.no_toc}
- `SLACK_WEBHOOK_URL` (**required**) - The webhook url that will be
used to post new comments to.
### talk-plugin-toxic-comments
## talk-plugin-toxic-comments
Source: [plugins/talk-plugin-toxic-comments](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-toxic-comments){:target="_blank"}
@@ -85,7 +84,6 @@ threshold. For more information on what Toxic Comments are, check out the
[Toxic Comments]({{ "/toxic-comments/" | relative_url }}) documentation.
Configuration:
{:.no_toc}
- `TALK_PERSPECTIVE_API_KEY` (**required**) - The API Key for Perspective. You
can register and get your own key at [http://perspectiveapi.com/](http://perspectiveapi.com/){:target="_blank"}.
@@ -97,7 +95,7 @@ Configuration:
be processed before it will skip the toxicity analysis, parsed by
[ms](https://www.npmjs.com/package/ms){:target="_blank"}. (Default `300ms`)
### talk-plugin-subscriber
## talk-plugin-subscriber
Source: [plugins/talk-plugin-subscriber](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-subscriber){:target="_blank"}
docs/_docs/03-04-plugin-recipes.md → docs/_docs/04-04-plugin-recipes.md
+4 -4
View File
@@ -16,7 +16,7 @@ The following are the available recipes for use:
{% include toc.html %}
### recipe-avatar
## recipe-avatar
Source: [talk-recipes/tree/master/plugins/avatar](https://github.com/coralproject/talk-recipes/tree/master/plugins/avatar){:target="_blank"}
@@ -24,7 +24,7 @@ Provides support for avatars hosted via third party, extends the User Model and
provides UI on the client-side too.
### recipe-translations
## recipe-translations
Source: [talk-recipes/tree/master/plugins/translations](https://github.com/coralproject/talk-recipes/tree/master/plugins/translations){:target="_blank"}
@@ -32,7 +32,7 @@ Provides an example for overriding application text through the translation
system.
### recipe-subscriber
## recipe-subscriber
Source: [talk-recipes/tree/master/plugins/subscriber](https://github.com/coralproject/talk-recipes/tree/master/plugins/subscriber){:target="_blank"}
@@ -41,7 +41,7 @@ Provides an example for adding `SUBSCRIBER` badges for users with the
the auth system.
### recipe-author-name
## recipe-author-name
Source: [talk-recipes/tree/master/plugins/author-name](https://github.com/coralproject/talk-recipes/tree/master/plugins/author-name){:target="_blank"}
docs/_docs/05-01-faq.md
+17
View File
@@ -0,0 +1,17 @@
---
title: FAQ
permalink: /faq/
---
## How can I get help integrating Talk into my newsroom?
We're here to help with newsrooms of all sizes. Email our Integration Engineer
([jeff@mozillafoundation.org](mailto:jeff@mozillafoundation.org)) to set up a meeting.
## How do I request a feature or submit a bug?
The best way is to [submit a Github issue](https://github.com/coralproject/talk/issues). Make sure you give plenty of details, our Core Team can usually respond within a few hours on weekdays.
## How can our dev team contribute to Talk?
We are lucky to work with newsroom dev teams and individual contributors who span the world, and come from newsrooms of all sizes. You can read our [Contribution Guide](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md) to get started, but feel free to reach out to us via Github, or get in touch directly with Jeff via jeff@mozillafoundation.org.
docs/_sass/talk.scss
+16 -7
View File
@@ -16,11 +16,25 @@ body {
}
h1 {
font-size: 1.7em;
font-size: 2rem;
}
h2, h3, h4 {
h2 {
margin: 1.6em 0 0.8em;
font-size: 1.75rem;
font-weight: 600;
}
h3 {
margin: 1.6em 0 0.8em;
font-size: 1.5rem;
font-weight: 500;
}
h4 {
margin: 1.6em 0 0.8em;
font-size: 1.2rem;
font-weight: 500;
}
.btn-coral {
@@ -41,10 +55,6 @@ h2, h3, h4 {
}
article.configuration {
h2 {
font-weight: bolder;
}
h2, .toc {
@extend .param;
}
@@ -411,4 +421,3 @@ a.brand {
}
}
}