Replace the static site editor text area with a WYSIWYG markdown editor
Problem to solve
Some contributors find writing in Markdown is unfamiliar or inefficient. The overhead required to mentally parse the syntax can distract from the content editing experience and often results in a lot of context switching and extraneous markup. For example, creating links, adding images, and editing tables are all actions that can be done more efficiently in a rich text or what-you-see-is-what-you-get (WYSIWYG) editor.
- Rachel (Release Manager)
- Parker (Product Manager)
- Delaney (Development Team Lead)
- Presley (Product Designer)
The goal of the static site editor feature is to abstract as much of the technical underpinnings of the markdown language and template architecture as possible to encourage collaboration across multiple personas, regardless of technical experience.
The raw text area in the current static site editor should be replaced with a WYSIWYG markdown editor, providing real-time rendering of content in vanilla HTML.
The editor we will be using is the ToastUI editor. We will be enabling the following capabilities for the editor
- Text sizing
- Heading selection
- Heading 1
- Heading 2
- Heading 3
- Heading 4
- Heading 5
- Heading 6
- Heading selection
- Text formatting
- Text enhancements
- List functionality
- Bullet list
- Numbered list
- Task list
- List indent
- List outdent
- Object insert
- Horizontal rule
- Inline code
- Make WYSIWYG view open by default
- Heading selection will leverage the dropdown that is built-in the ToastUI editor
- Headers should be rendered visually distinct and consistent with the GitLab CSS rules.
Support for rendering and editing markdown tables will be done with ToastUI's built in functionality:
- Inserting a new table
- Editing a table cell
- Adding/removing a row/column
- Available when the user right clicks the row/column
What are we not doing (yet)
// TODO: Is excluding image uploads actually more work than using Toast UI's built in image support? If we chose a default location to put assets, would this just work out of the box?
- We will not be implementing a way to visually upload images or access any kind of asset library in this release. If images are added, it is by providing a direct or relative URL only.
- Code snippets as a content source
- A common pattern in visual markdown editors is to provide autocomplete formatting shortcuts. Fo example, when the user types
space, the hashes are removed and the line of text is formatted as an H2.
- Images (from URL only)
- Pasting CSV data from the clipboard to generate the table
- Text Formatting
- Underline (not supported by ToastUI and may be confusing with links. Suggested for writers to use bold to emphasis text)
Latest design: Text_editor_introduction.png
Permissions and Security
No additional permissions are changed with this feature
- Add all known Documentation Requirements in this section. See https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#documentation-requirements
- If this feature requires changing permissions, update the permissions document. See https://docs.gitlab.com/ee/user/permissions.html -->
Availability & Testing
What does success look like, and how can we measure that?
We have yet to instrument this feature for usage data
A user can edit the content of a realistically complex page without writing a single line of markdown.
Is this a cross-stage feature?
WYSIWYG editing is something that's being explored by multiple groups. Our goal is to move fast so we can test the editing experience and the WYSIWYG editor is a big part of that. The Static Site Editor group will be sharing any learnings about integrating the WYSIWYG editor with the rest of Create and Plan. By maintaining a loosely-coupled relationship between our feature and the editor itself, we will be able to pivot to a different editor quickly if another group provides a better solution.