Commit 9e46bdd2 authored by Eric Eastwood's avatar Eric Eastwood

Move information from Gitter topics to tracked markdown docs

Topics was deprecated and will be removed soon so we need the info in a new canonical place, #1947
parent 8c2e3f87
......@@ -31,6 +31,8 @@ for the ability to customize your username in the future and remove the suffix.
Sign out of Gitter and sign back in to update your avatar (or any other info).
Currently, there is an outstanding bug where this doesn't work with GitLab/Twitter accounts,
## How do I delete my account?
......@@ -2,16 +2,23 @@
A community holds many rooms.
Communities are also referred to as "groups" internally.
Communities are also referred to as "groups" internally in the codebase.
## Community creation
Use the "+" button in the bottom-left of the menu bar to start the community creation process
Use the "+" button in the bottom-left of the menu bar to start the community creation process.
Communities can be associated with a GitHub organisation or repo. If you don't see the GitHub org/repo listed that you want to associate, see [*Why isn't my GitHub organisation or repos appearing?* FAQ](./]
## Community admins
You can add new admins for a room by visiting a room in the community -> **Room settings dropdown** -> **Permissions** modal -> **Edit community permissions**
## Rename a community
If you want to rename a community because a GitHub org/repo was renamed/transferred, see this [FAQ section instead](./ instead.
# Customization
## Dark theme
You can toggle the dark theme via the profile menu dropdown in the top-right -> **Toggle Dark Theme**
......@@ -6,6 +6,26 @@ Frequently asked questions.
Gitter is entirely free for all public and private conversations.
## I have a suggestion, where can I suggest/discuss it?
Feel free to come discuss your idea in the [`gitterHQ/gitter`]( room and create an issue,
## Help/Support!?!?!
If your support inquiry doesn't need to be private, drop by the [`gitterHQ/gitter`]( room.
Otheriwse, send a message to
## Do you have an API?
Why, we are so gladded you asked, **yes** we do.
You can build apps on top of Gitter by using our REST API. You can find more information about it at []( or use our [Node.js module](
If you have any questions about our API, please don't hesitate to contact us or join us in our [`gitterHQ/api`]( chat room.
## Can I merge/connect my accounts?
......@@ -27,6 +47,11 @@ See [Accounts](./
See [Accounts](./
## You want write access on my private repos? Are you insane?
See ["Private Repositories" on the OAuth scopes page](./
## Why isn't my GitHub organisation or repos appearing?
The first thing to check is [adding private repo access OAuth scope](./ in order to see a private GitHub repo.
......@@ -46,10 +71,6 @@ You can also try making your organisation membership public, `
For more information see [OAuth Scopes](./
## You want write access on my private repos? Are you insane?
See ["Private Repositories" on the OAuth scopes page](./
## What happens if I rename something on GitHub (org, repo)
#### Org rename
......@@ -87,3 +108,29 @@ Send a message to with the following info. Make sure to email
- Link to where the repo now exists on GitHub
- Link to the old room on Gitter
- Link to the new room on Gitter
## What is Gitter Next?
Gitter Next is where we put our up-coming release branch up for preview. Most of the time it's small changes or even under-the-hood changes you don't see. Sometimes we put pretty large changes up there too and love to hear your feedback.
Sometimes it blows up, but not very often.
You can enable Gitter next in a variety of ways.
#### Desktop Browser
In your desktop browser, visit and move the giant switchy thing over to next. Then refresh. You will notice a little green pill at the top of your screen that says "NEXT". You are now on Next.
There's also a bookmarklet at the bottom of the Next page and you can add this to your browser things to toggle this pretty easily.
#### Linux and Windows app
There's a convenient little toggle on the Gitter menu of your application to turn Next on or off.
#### Mac app
**Gitter** menu bar dropdown in the top-left -> **Use Gitter Next**
# Feature Toggles
Various features on Gitter are hidden behind a feature toggle. It is best to [enable Next](./ when using these features.
Some features are experimental and it is best not to just enable everything as they could easily break some things as they are developed.
## Using Gitter in your browser?
Simply visit []( and make sure the big giant Next switch is enabled, then find the left-menu toggle further down the screen and enable it. Refresh Gitter and you should be good to go.
## Windows or Linux App
If you use Gitter on Windows or Linux, it's a little fiddlier than that. Click on the Gitter menu in the top-bar and make sure Gitter Next is enabled. Then click on Developer Tools which will bring up a window and select the Console tab. Find the select box that defaults to <top frame> at the top of the console and change the value to mainframe. Once that's done, paste the following code into the console and press Enter.
document.cookie = 'fflip=' + encodeURIComponent('j:' + JSON.stringify({ 'some-feature-toggle': true })) + ';path=/;expires=' + new Date( + 31536000000).toUTCString();
## Mac App
Make sure Enable Developer Tools is enabled from the Gitter menu in the top bar. Right click anywhere in the application and choose Inspect Element. This will bring up a web console, just paste the following code snippet into the console and press Enter. The app will refresh after a second or so.
document.cookie = 'fflip=' + encodeURIComponent('j:' + JSON.stringify({ 'some-feature-toggle': true })) + ';path=/;expires=' + new Date( + 31536000000).toUTCString();
......@@ -6,10 +6,16 @@
- [FAQ](./
- [Gitter accounts](./
- [Mobile apps (Android/iOS)](./
- [Rooms](./
- [Desktop app](
- [Keyboard shortcuts](./
- [Customization](./
- [Communities](./
- [Rooms](./
- [Messages](./
- [Notifications](./
- [OAuth Scopes](./
- [Integrations/Activity](./
- [Feature toggles](./
## Developers
# Integrations/Activity
Gitter is integrated with numerous services via webhooks. When you add an integration to a chat room, you will see events from that integration appear in the right-toolbar under the "Activity" section.
Our integrations include:
- GitLab
- GitHub
- BitBucket
- Trello
- AppVeyor
- CircleCI
- Codecov
- Codeship
- Coveralls
- Discourse
- Docker Hub
- Doorbell
- Drone
- GitBook
- GoCD
- Heroku
- Huboard
- Jenkins
- Logentries
- New Relic
- Open Collective
- PagerDuty
- Pivotal Tracker
- Sentry
- SnapCI
- The Bug Geneie
- TrackJS
- Travis
- Send us a Merge request to add your own,
## Setup
**Room settings dropdown** -> **Integrations**
# Keyboard shortcuts
You can find a list of our shortcuts with any of the following methods,
- Click the `M↓` icon to the right of the chat input area then click the **Keyboard shortuts** button at the bottom
- `?` general keyboard shortcut
- `Cmd + Ctrl + k` keyboard shortcut on macOS
- `Ctrl + Shift + k` keyboard shortcut on Windows.
# Dark arts of the left menu
The left menu lists all of your conversations. It also contains a few cunningly awesome features.
Firstly, understanding how the left menu is ordered is important. Any chat rooms or people that have been **favourited** will show first, followed by chat rooms where there are **unread notifications** and finally other chat rooms ordered by the time you last accessed them.
So that's basically:
- Favourites
- Unread notifications
- Recents
If you click and drag any room below **favourites**, you can move it up into the favourites list. You can also explicitly order favourites by dragging them around.
Items below the favourites cannot be ordered as they are ordered by unread or recent activity.
You can also drag a room out of favourites. This will remove it from your favourites and it will automatically be positioned in the list below based on when it was last accessed as per all of the other recent rooms.
## Hiding rooms
It is also possible to hide a room from this list. If you receive a notification for the room again, it will reappear. If you no longer wish to receive notifications from that room, you should either leave that room (`/leave` slash command) or change notifications to mentions only. You cannot hide a one to one room.
# Messages
All rooms have unlimited message history, public or private.
## Writing messages
By default, hitting Enter when a chat message is typed will send the message, **Chat mode**. If you want to write multi-line messages, you can either insert a line break manually (Shift + Enter). Alternatively, you can toggle **Compose mode** where Enter will add a line break without sending a message (Ctrl + Enter will send the message).
There is also toggle button that can be found to the right of the chat input area and will look like the following two icons depending on which mode is activated.
Chat Mode | Compose Mode
--- | ---
![]( | ![](
Additionally, if you type three backticks followed by Enter, we will automagically toggle compose mode (as well as close your backticks for you) so you can easily type in code. When you send the message, compose mode will get toggled back off. Neat, huh?
#### Keyboard shortcuts
`Ctrl + /`: Toggle Normal/Compose Mode
**Normal Mode**
- `Enter` - to send message
- `Shift + Enter` - to go to new line
**Compose Mode**
- `Enter` - to go to new line
- `Shift + Enter` - to go to new line (behaves same as `Enter`)
- `Ctrl + Enter` - to send message
## Message syntax
### Markdown
This is probably one of the reasons you are here in the first place. Gitter supports markdown in chat. Yes, that's right. Markdown. In Chat. Such win.
We not only support basic markdown, but also we do syntax highlighting for code and also support issue mentions and @ mentions.
For those unfamiliar with markdown, [GitLab has a nice Markdown reference doc]( You can access a simple guide in the Gitter application by clicking on the `M↓` icon to the right of the chat input area.
### KaTeX (math formulas)
We also support [KaTeX]( syntax for math/scientific formula notation.
Before | After
--- | ---
`$$ f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi $$` | ![](
### Mentions
You can directly mention someone else using the `@username` syntax. As you type their username or real name, it should appear in the typeahead for autocompletion.
If the person you mention has notifications enabled, they will see a notification that they have been mentioned.
### Issuable decorations
When you paste a link to a GitLab/GitHub issue, merge request, or pull request it will decorate into a special link where you can preview the contents without having to click through.
## Slash commands
We support a few /commands and will continue to add new ones. At the moment, you can do any of the commands listed below.
- `/leave`: Leaves the chat room.
- `/query @username`: Go 1:1 with `@username`.
- `/fav`: Toggles the room as a favourite.
- `/topic <some imaginative and brilliant description>`: Set the topic of the room to "some imaginative and brilliant text".
- `/notify-all`: Switch the room to notify you for all messages
- `/notify-announcements`: Switch the room to notify you for direct mentions and `@/all` announcements
- `/notify-mute`: Switch the room to notify you only for direct mentions
- `/me <some message>`: If you know IRC, you'll know what this does
- `/remove @username`: Removes a user from a conversation. Only available to owners/admin of the conversation.
- `/ban @username`: Bans a user from a conversation. Only available to owners/admins in public rooms.
- `/unban @username`: Unbans a user from a conversation. Only available to owners/admins in public rooms.
- `/collapse`: Collapse the first chat message with embedded media
## Edit messages
You can edit your own messages within the 5 minute edit window. The **Edit** option is available in the message `...` dropdown in the top-right of every message.
You can quickly jump to editing your last message by using the up-arrow keyboard interaction.
## Searching messages
Search is located in the left menu under the magnifying glass menu bar icon. You can press **Ctrl/Cmd + S** to jump straight to that view.
Search will find rooms across Gitter and messages in the current room.
You can use the `from:username` syntax to only find messages from the specified user (filter).
## Message archive
You can access a rooms message archive via the **Room settings dropdown** -> **Arhives**.
The archive heatmap currently only shows a year but you can manually navigate by changing the URL. You can [track this issue for increasing the heatmap size](
## Tips for crafting a great message
Some tips to improve your chances of getting a quick response and a great interaction.
### Do's
- Be patient
- Describe what you are trying to do, what you have tried so far, and what kind of behavior you are expecting
- Share a link to what you are talking about
- Create a demo on [jsFiddle](, [CodePen](, etc
- Use \`inline code\`, or actual code _blocks_ (```) when sharing code. We support markdown
- Use complete sentences and proper grammar, it just makes your question a pain to read otherwise
- If you figure out a solution to your problem after proposing a question, please post your answer so others don't waste their time trying to answer. It's also a good reference for future onlookers
### Don'ts
- [Don't ask to ask, just ask your actual question directly](
- Don't just say "Hello" or introduce yourself and wait for someone to respond, just ask your question
- Don't ask if anyone is around
- Don't ask if anyone is familiar with or knows about a specific thing that you are trying to use
- Don't post across many rooms (cross posting). Post in the most relevant room and be patient
- Don't ask people to respond to you in a one to one conversation
......@@ -2,7 +2,31 @@
Rooms are part of a community.
Rooms are also referred to as "troupes" internally for legacy reasons.
Rooms are also referred to as "troupes" internally in the codebase for legacy reasons.
All rooms have unlimited message history, public or private.
## People/Roster
You can see who is in the room and add/invite new users via the roster section in the right-toolbar
#### Eyeballs Disambiguation
Eyeballs are the green and yellow/orange dots on top of the avatars in the people section of a room. They represent the current status or online presence of a person in the room.
So what does each color mean?
- **Green**: Actively looking at the room
- **Yellow/Orange**: Not actively looking at the room
"Actively looking" equates to whether the window has focus and the room is open.
## Room user
......@@ -32,6 +56,7 @@ If you don't see the repo listed in the typeahead or isn't being associated, see
#### Why isn't my GitHub organisation or repos appearing?
See the [FAQ](./
......@@ -50,6 +75,23 @@ See the [FAQ](./
- A private room can also be associated with the community and anyone in the community can join the room. If the community was associated with an org, anyone in the org could join for example
### Room topic/description
A room topic/description will help the community members and new people joining to know what's the purpose of the room.
To set up your room topic, double-click on the area next to the room name in the chat header.
You can also use the `/topic <some topic message>` slash command to set the room topic.
### Moderation
As an admin of the room, you can delete messages from other users.
You can add new admins for a room via **Room settings dropdown** -> **Permissions** modal
### Restrict room to GitHub users
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment