Skip to content

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.

Intended users

Further details

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.

Proposal

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.

Editor Toolbar

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
      • Paragraph
  • Text formatting
    • Bold
    • Italic
    • Strikethrough
  • Text enhancements
    • Quote
    • Link
    • Codeblock
  • List functionality
    • Bullet list
    • Numbered list
    • Task list
    • List indent
    • List outdent
  • Object insert
    • Horizontal rule
    • Table
    • Inline code

Editor Behaviour

  • 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.

Table support

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 ## then 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)

Design

Latest design: Text_editor_introduction.png

Figma Spec: https://www.figma.com/file/RhYal9t4OZk7IeYsSvEHpW/WYSIWYG-markdown-editor-214559?node-id=108%3A70

Permissions and Security

No additional permissions are changed with this feature

Documentation

Availability & Testing

What does success look like, and how can we measure that?

Success metrics

We have yet to instrument this feature for usage data

Acceptance criteria

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.

Edited by Michael Le