UX Documentation

The ‘Advanced Text Editor’ is a feature intended to aid users who might not be used to the markdown formatting syntax.

For users who are familiar with Markdown, this feature also adds in some shortcuts (e.g. Command+B for Bold) for formatting with markdown that will help format messages more quickly.

Prototype and Design

You can view the prototype and design work for this feature with the links below. NOTE: user COMMAND/CTRL . to open the RHS

• Figma Prototype

• Figma Design File - use the ‘Inspect’ view to see dimensions and code attributes

Updates to the Message Draft Component

The Message Draft Component has a new ‘Show formatting' button that displays next to the attachment and emoji icons.

States

Formatting Bar Closed

Open

• A tooltip shows when hovering over this button.

• When clicked, the formatting bar is opened and the button changes to the ‘active’ state (see below)

Formatting Bar Open

When the formatting bar is opened users have quick access to standard markdown formatting for their message. In addition, a Preview button (eye icon) is added to show a preview of what they’re formatting (similar to existing experimental preview function)

Open

Remembering Open/Closed State

The state of the formatting bar (open/closed) will persist. The hypothesis is that this will be something users turn on once and won’t want to turn it off very often (although they can easily do so).

Default State

The formatting bar will be open by default once the feature is released.

The Formatting Bar

Controls

The following controls are displayed when the formatting bar is opened:

• Bold

• Italic

• Strikethrough

• Headings

• Links

• Code formatting

• Quote

• Bulleted Lists

• Numbered Lists

• Help (shows current message help in new window)

• Preview

Behavior for each of the controls

Tooltips

• When hovering over one of the formatting buttons, tooltips (with shortcuts if applicable) show after a user has hovered for 800 ms.

• NOTE: there is a separate ticket to complete the UI for displaying shortcuts in tooltips

NOTE: Much of the behavior notes below are derived from Github’s markdown formatting bar.

Bold, Italic, Strikethrough Buttons

• When the cursor is at the beginning of an empty message draft, add the markdown formatting characters. The cursor is placed in between the opening and closing characters. (e.g. **|** )

• When text is selected, surround the selected text with the opening and closing characters (e.g. **selected text**). The text remains selected

• When the cursor is at the beginning of a word, surround the word with the formatting characters (e.g. **word**. The cursor remains at the beginning of the word (e.g. **|word**)

• When the cursor is in the middle of a word, surround the word with the formatting characters (e.g. **word**. The cursor remains in the middle of the word (e.g. **wo|rd**)

• When the cursor is at the end of a word (that is not the last word), surround the word with the formatting characters (e.g. **word**). The cursor remains at the end of the word (e.g. **word|**)

• If the nearby or selected text is already formatted with the style, clicking the button will remove the corresponding markdown characters from the word/selection.

• When the cursor is at the end of the last word in a line, add a space and then the markdown formatting characters after the last word. The cursor is placed in between the opening and closing characters. (e.g. **|** )

• When the cursor has a space on either side or is at the end of a line after a space, add the markdown formatting characters after the last word. The cursor is placed in between the opening and closing characters. (e.g. **|** )

Headings Button

• Initially, only supporting H3 headings (###).

• When the cursor is at the beginning of an empty message draft, add the heading characters (e.g. ### ). The cursor is placed after the heading characters (e.g. ### | )

• When the cursor is anywhere else, add the heading characters (e.g. ### ) to the beginning of the current line. The cursor remains where it was.

• When text is selected, add the heading characters (e.g. ### ) to the beginning of the current line. The text remains selected.

• If multiple lines are selected, add the heading characters (e.g. ### ) to the beginning of each line that has a line break. The text remains selected.

Link Button

• When the cursor is at the beginning of an empty message draft, add [](url) to the message draft. The cursor is placed in between the []. (e.g. [|](url) )

• When text is selected, add [](url), but the selected text is placed within the [] (e.g. [selected text](url)). url gets selected.

• When the cursor is at the beginning of a word, add [](url), but the nearby word is placed within the [] (e.g. [nearby word](url)). url gets selected.

• When the cursor is in the middle of a word, add [](url), but the nearby word is placed within the [] (e.g. [nearby word](url)). url gets selected.

• When the cursor is at the end of a word (that is not the last word), add [](url), but the nearby word is placed within the [] (e.g. [selected](url)). url gets selected.

• When the cursor is at the end of the last word in a line, add [](url) to the message draft. The cursor is placed in between the []. (e.g. [|](url) )

Code Button

• When the cursor is on a blank line with no text, insert the opening code block characters ( ``` ) add a blank line and then add the closing ``` characters. Place the cursor on the blank line between the code block characters.

• ``` ```

• When text is selected (as long as it’s not more than one line), surround the selected text with single ` characters (e.g. `selected text`). The text remains selected.

• If more than one line of text is selected, surround the selected text with ``` characters above and below the selected text. The text remains selected. For example:

• When the cursor is at the beginning of a word, surround the word with the single ` characters (e.g. `word`. The cursor remains at the beginning of the word (e.g. `|word`)

• When the cursor is at the end of a word (but is not the last word), surround the word with the single ` characters (e.g. `word`). The cursor is placed at the end of the word (`word|`)

• When the cursor is at the end of the last word in a line, add ``` characters with a blank line then the closing ``` characters. Place the cursor on the blank line between the code block characters on the blank line.

Quotes Button

• When the cursor is at the beginning of an empty message draft, add the quote character (e.g. > ). The cursor is placed after the quote character (e.g. > | )

• When the cursor is anywhere else, add the quote character (e.g. > ) to the beginning of the current line. The cursor remains where it was.

• When text is selected, add the quote character (e.g. > ) to the beginning of the current line. The text remains selected.

• When multiple lines are selected only add the the > to the first line - unless there is a blank line between. If there is a blank line add another > for each paragraph separated by a blank line

Bulleted List Button

• When the cursor is at the beginning of an empty message draft, add the bullet character (e.g. - ). The cursor is placed after the character (e.g. - | )

• When the cursor is anywhere else, add the bullet character (- ) to the beginning of the current line. The cursor remains where it was.

• When text is selected, add the bullet character (- ) to the beginning of the current line. The text remains selected.

• When multiple lines are selected, add the bullet character (- ) to each of the selected lines that has a line break

Numbered List Button

• When the cursor is at the beginning of an empty message draft, add the numbered list characters (e.g. 1. ). The cursor is placed after the characters (e.g. 1. | )

• When the cursor is anywhere else, add the numbered list character (1. ) to the beginning of the current line. The cursor remains where it was.

• When text is selected, add the numbered list character (1. ) to the beginning of the current line. The text remains selected.

• When multiple lines are selected, add the numbered list character (1. ) to each of the selected lines that has a line break and also sequence the numbers

Preview Button

• Default off

• When on, shows the rendered preview of the markdown so you can see what the result of your markdown will be before sending

• When on, disables all editing controls in the formatting bar

• Users can still press ENTER to send

Responsive Width Behaviour

• As the component’s width gets narrower, the formatting controls collapse in to a ••• icon button

• When the ••• button is clicked it triggers a popout menu with the additional controls

The Message Draft in the Right Sidebar

Following similar rules as above, the Message Draft Input displays like below in the RHS context.

Formatting Bar Closed

In the RHS context, the message draft displays taller and the icons anchor to the bottom right.

Formatting Bar Open

In the RHS context, when the formatting bar is open it displays in a condensed form, hiding additional controls in the ••• icon button.

Mobile Web View

Following similar rules as above, with a few additional details for mobile views.

• Space out icons more

• Adds ‘Send’ button

• Slightly different focus state

See Figma file for more details on the responsive views.

Shortcuts

The following shortcuts are currently implemented. See the Future Proposed Enhancements page for additional proposed shortcuts.

Settings

Account Settings

We will need to remove the “Show markdown preview option in message input box” setting from Account Settings > Advanced > Preview Pre-release Features. This setting will be deprecated when the Advanced Text Editor feature is released.

System Console Settings

We will need to add a config setting to enable the Advanced Text Editor feature. In the System Console > Posts page below “Enable Link Previews”, add a setting for:

Enable Text Formatting Controls: [ x ] true [ ] false
When enabled, users can choose to show text formatting buttons in the message composition area.