openedx / openedx/frontend-app-authoring
The "Markdown" editor has never supported real Markdown
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:
- "Markdown" (default), a human-readable text format, with some formatting buttons. Also supports HTML.
- "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:
- WSIWYG (default), which allows users to build most kinds of of Problems (but not multipart Problems, yet).
- "Markdown", which was originally omitted from the React-based editor, but was recently added back in Teak.
- "Advanced".
Open edX "markdown" syntax
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
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- 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