openedx / openedx/frontend-app-authoring

The "Markdown" editor has never supported real Markdown

Open
#2,444 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
17
Forks
218
Avg merge
9d 20h
Merged PRs (30d)
20

Description

Background

The legacy Problem editor only supported two modes:

  1. "Markdown" (default), a human-readable text format, with some formatting buttons. Also supports HTML.
  2. "Advanced", a code editor displaying the raw underlying OLX (Open Learning XML).

The new React-based problem editor, which is now the default, supports three modes:

  1. WSIWYG (default), which allows users to build most kinds of of Problems (but not multipart Problems, yet).
  2. "Markdown", which was originally omitted from the React-based editor, but was recently added back in Teak.
  3. "Advanced".
Open edX "markdown" syntax
Image Image

The Issue

Our "Markdown" mode is not actually Markdown! It's a custom format that edX invented back in 2011 which hilariously has no syntax features in common with actual Markdown. This is true of both the legacy and new react-based "markdown" problem editors.

The Markdown formats supported by common tools like Slack, GitHub, Discord, Reddit, etc. all have some variation. However, unlike Open edX, their Markdown editors all share common syntax for common formatting pattern like bold, italic, headings, and links

### Real markdown example

This is **bold**, this is _italic_, and this is a [link](https://example.com). 

I'm not sure why the platform ever called our format "markdown". Maybe it was based in confusion, or maybe it was based in an aspirational future expansion of that formatting language.

Fixes

There are two approaches we could take. We could also do the "Easy fix" now, and leave the "Harder fix" open as an option for the future.

Easy fix: Rename the editing mode

Instead of "Markdown", it could be "Text-based", or the "Legacy mode", or something like that. This would be an easy UI change to make, and it would resolve the issue.

There are a lot of references to "Markdown" in the code. We can refactor some of those, and others we'd just have to leave as-is with some explanatory comments.

Harder fix: Add support for real markdown syntax in to the editor

This is possible, but it would probably take multiple developer-weeks, and we would need to think carefully about backcompat. We'd probably need some indicator within the data of a Problem block to indicate that it is using "real" markdown; that way, when we render old ("fake mardown") problems, we wouldn't suprise authors by turning asterisks into italics, brackets into links, etc.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the React problem editor and every code reference to the "Markdown" mode. Compare the legacy and new editor behavior described in the issue, then determine which approach is selected: renaming the mode or adding real Markdown with backward compatibility. Done means the chosen behavior is implemented consistently without changing existing problem interpretation unexpectedly.

Written by the indexing model from the issue text.

Assessment

Tech stack
react, typescript
Domain
frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
28/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.