Designing and building a Markdown Editor

May 20, 2020 3 min read

Markdown Editor

The problem

At Elastic, we needed a component that would allow writing technical content. This content could contain code, images, attached files, or even embeddable components.

That's why we decided to build a Markdown editor. This component would allow us to write content in Markdown and preview it in real time. This was the first component I designed and built from scratch at Elastic. So it has a special place in my heart.

Known use cases

As a team we decided to create a feature specification where we would list all the features we wanted to implement in the editor. We also wanted to make sure that the editor would be flexible enough to be used in different contexts.

We've identified the following use cases:

  • Incident tracking and case management
  • General user-to-user communication
  • Rich content dashboard panels
  • Add text to Dashboards
  • Replace simple textarea in Canvas
  • Annotations to visualizations
  • Text annotation in Maps
  • Write email templates for Alerts

Early exploration phase

This early exploration phase allowed me to explore different directions and to test different ideas.

  • How is it going to look? Toolbar, textarea and preview.
  • Get conceptual mocks to a place that shows how to embed a visualization. Hitting a button in the toolbar.

First designs in Figma

So I started by designing in Figma. First, just how the write and preview features would look like.

Markdown Editor

Then how the drag and drop feature would look like.

Markdown Editor

User flows in Figma

Then I started to explore user flows. I wanted to make sure that the plugin would be easy to use and that the user would be able to understand how to use it.

Markdown Editor

Figuring out error states

I also add to figure out the error states. I wanted to make sure that the user would understand what was going on and that the error messages would be clear.

Markdown Editor

Implementation and documentation

After all the design I started to implement the UI for the editor. I created a coded prototype with all the required states. My colleague, Chandler Prall was responsible for implementing the plugin API. We worked together to make sure that the plugin API was flexible enough to be used in different contexts. Dave Snider, my manager at the time, helped us writing part of the documentation. You can find the documentation here. Caroline Horn, who was a more senior designer was responsible to provide guidance and mentoring.


In the future, we want to add the ability to tag a user or a project inside the editor. So we can easily mention someone or link to a project. We're already working on this feature.


This was a great experience. I learned a lot about how to design and build a component from scratch. I also learned a lot about how to work with a team and how to collaborate with other designers and developers. I'm really happy with the result and I'm looking forward to working on more projects like this one.

Share on TwitterEdit on GitHub


© 2022-present Elizabet Oliveira