diff --git a/docs/_data/nav.yaml b/docs/_data/nav.yaml index eeb7c2ebc..9138d6603 100644 --- a/docs/_data/nav.yaml +++ b/docs/_data/nav.yaml @@ -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/ diff --git a/docs/_docs/02-01-required-configuration.md b/docs/_docs/02-01-required-configuration.md index 84a7236db..dc09a1707 100644 --- a/docs/_docs/02-01-required-configuration.md +++ b/docs/_docs/02-01-required-configuration.md @@ -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://:@:` 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" 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`) diff --git a/docs/_docs/04-01-product-guide-how-talk-works.md b/docs/_docs/03-01-product-guide-how-talk-works.md similarity index 100% rename from docs/_docs/04-01-product-guide-how-talk-works.md rename to docs/_docs/03-01-product-guide-how-talk-works.md diff --git a/docs/_docs/03-02-product-guide-commenter-features.md b/docs/_docs/03-02-product-guide-commenter-features.md new file mode 100644 index 000000000..b46c5f054 --- /dev/null +++ b/docs/_docs/03-02-product-guide-commenter-features.md @@ -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://?commentId= +``` +{:.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. diff --git a/docs/_docs/03-03-product-guide-moderator-features.md b/docs/_docs/03-03-product-guide-moderator-features.md new file mode 100644 index 000000000..45516b1a5 --- /dev/null +++ b/docs/_docs/03-03-product-guide-moderator-features.md @@ -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. diff --git a/docs/_docs/04-02-product-guide-trust.md b/docs/_docs/03-04-product-guide-trust.md similarity index 96% rename from docs/_docs/04-02-product-guide-trust.md rename to docs/_docs/03-04-product-guide-trust.md index 42587d203..396ecd07d 100644 --- a/docs/_docs/04-02-product-guide-trust.md +++ b/docs/_docs/03-04-product-guide-trust.md @@ -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, diff --git a/docs/_docs/04-03-product-guide-toxic-comments.md b/docs/_docs/03-05-product-guide-toxic-comments.md similarity index 96% rename from docs/_docs/04-03-product-guide-toxic-comments.md rename to docs/_docs/03-05-product-guide-toxic-comments.md index 56677a421..ac680916d 100644 --- a/docs/_docs/04-03-product-guide-toxic-comments.md +++ b/docs/_docs/03-05-product-guide-toxic-comments.md @@ -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/). diff --git a/docs/_docs/03-06-product-guide-configuring-talk.md b/docs/_docs/03-06-product-guide-configuring-talk.md new file mode 100644 index 000000000..ba6647435 --- /dev/null +++ b/docs/_docs/03-06-product-guide-configuring-talk.md @@ -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! diff --git a/docs/_docs/03-01-plugins-overview.md b/docs/_docs/04-01-plugins-overview.md similarity index 100% rename from docs/_docs/03-01-plugins-overview.md rename to docs/_docs/04-01-plugins-overview.md diff --git a/docs/_docs/03-02-default-plugins.md b/docs/_docs/04-02-default-plugins.md similarity index 88% rename from docs/_docs/03-02-default-plugins.md rename to docs/_docs/04-02-default-plugins.md index ab843f21b..5c987172d 100644 --- a/docs/_docs/03-02-default-plugins.md +++ b/docs/_docs/04-02-default-plugins.md @@ -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"} diff --git a/docs/_docs/03-03-additional-plugins.md b/docs/_docs/04-03-additional-plugins.md similarity index 93% rename from docs/_docs/03-03-additional-plugins.md rename to docs/_docs/04-03-additional-plugins.md index 9be7f1cd2..55ab1749b 100644 --- a/docs/_docs/03-03-additional-plugins.md +++ b/docs/_docs/04-03-additional-plugins.md @@ -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"} diff --git a/docs/_docs/03-04-plugin-recipes.md b/docs/_docs/04-04-plugin-recipes.md similarity index 95% rename from docs/_docs/03-04-plugin-recipes.md rename to docs/_docs/04-04-plugin-recipes.md index 6b76a54ca..019ff21e4 100644 --- a/docs/_docs/03-04-plugin-recipes.md +++ b/docs/_docs/04-04-plugin-recipes.md @@ -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"} diff --git a/docs/_docs/05-01-faq.md b/docs/_docs/05-01-faq.md new file mode 100644 index 000000000..06d0b0669 --- /dev/null +++ b/docs/_docs/05-01-faq.md @@ -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. diff --git a/docs/_sass/talk.scss b/docs/_sass/talk.scss index 85e5f1c93..e967d10e4 100644 --- a/docs/_sass/talk.scss +++ b/docs/_sass/talk.scss @@ -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 { } } } -