diff --git a/docs/slate-formats.md b/docs/slate-formats.md deleted file mode 100644 index 7bb2fc9c5f..0000000000 --- a/docs/slate-formats.md +++ /dev/null @@ -1,88 +0,0 @@ -Guide to data types used by the Slate-based Rich Text Editor ------------------------------------------------------------- - -We always store the Slate editor state in its Value form. - -The schema for the Value is the same whether the editor is in MD or rich text mode, and is currently (rather arbitrarily) -dictated by the schema expected by slate-md-serializer, simply because it was the only bit of the pipeline which -has opinions on the schema. (slate-html-serializer lets you define how to serialize whatever schema you like). - -The BLOCK_TAGS and MARK_TAGS give the mapping from HTML tags to the schema's node types (for blocks, which describe -block content like divs, and marks, which describe inline formatted sections like spans). - -We use <p/> as the parent tag for the message (XXX: although some tags are technically not allowed to be nested within p's) - -Various conversions are performed as content is moved between HTML, MD, and plaintext representations of HTML and MD. - -The primitives used are: - - * Markdown.js - models commonmark-formatted MD strings (as entered by the composer in MD mode) - * toHtml() - renders them to HTML suitable for sending on the wire - * isPlainText() - checks whether the parsed MD contains anything other than simple text. - * toPlainText() - renders MD to plain text in order to remove backslashes. Only works if the MD is already plaintext (otherwise it just emits HTML) - - * slate-html-serializer - * converts Values to HTML (serialising) using our schema rules - * converts HTML to Values (deserialising) using our schema rules - - * slate-md-serializer - * converts rich Values to MD strings (serialising) but using a non-commonmark generic MD dialect. - * This should use commonmark, but we use the serializer here for expedience rather than writing a commonmark one. - - * slate-plain-serializer - * converts Values to plain text strings (serialising them) by concatenating the strings together - * converts Values from plain text strings (deserialiasing them). - * Used to initialise the editor by deserializing "" into a Value. Apparently this is the idiomatic way to initialise a blank editor. - * Used (as a bodge) to turn a rich text editor into a MD editor, when deserialising the converted MD string of the editor into a value - - * PlainWithPillsSerializer - * A fork of slate-plain-serializer which is aware of Pills (hence the name) and Emoji. - * It can be configured to output Pills as: - * "plain": Pills are rendered via their 'completion' text - e.g. 'Matthew'; used for sending messages) - * "md": Pills are rendered as MD, e.g. [Matthew](https://matrix.to/#/@matthew:matrix.org) ) - * "id": Pills are rendered as IDs, e.g. '@matthew:matrix.org' (used for authoring / commands) - * Emoji nodes are converted to inline utf8 emoji. - -The actual conversion transitions are: - - * Quoting: - * The message being quoted is taken as HTML - * ...and deserialised into a Value - * ...and then serialised into MD via slate-md-serializer if the editor is in MD mode - - * Roundtripping between MD and rich text editor mode - * From MD to richtext (mdToRichEditorState): - * Serialise the MD-format Value to a MD string (converting pills to MD) with PlainWithPillsSerializer in 'md' mode - * Convert that MD string to HTML via Markdown.js - * Deserialise that Value to HTML via slate-html-serializer - * From richtext to MD (richToMdEditorState): - * Serialise the richtext-format Value to a MD string with slate-md-serializer (XXX: this should use commonmark) - * Deserialise that to a plain text value via slate-plain-serializer - - * Loading history in one format into an editor which is in the other format - * Uses the same functions as for roundtripping - - * Scanning the editor for a slash command - * If the editor is a single line node starting with /, then serialize it to a string with PlainWithPillsSerializer in 'id' mode - So that pills get converted to IDs suitable for commands being passed around - - * Sending messages - * In RT mode: - * If there is rich content, serialize the RT-format Value to HTML body via slate-html-serializer - * Serialize the RT-format Value to the plain text fallback via PlainWithPillsSerializer in 'plain' mode - * In MD mode: - * Serialize the MD-format Value into an MD string with PlainWithPillsSerializer in 'md' mode - * Parse the string with Markdown.js - * If it contains no formatting: - * Send as plaintext (as taken from Markdown.toPlainText()) - * Otherwise - * Send as HTML (as taken from Markdown.toHtml()) - * Serialize the RT-format Value to the plain text fallback via PlainWithPillsSerializer in 'plain' mode - - * Pasting HTML - * Deserialize HTML to a RT Value via slate-html-serializer - * In RT mode, insert it straight into the editor as a fragment - * In MD mode, serialise it to an MD string via slate-md-serializer and then insert the string into the editor as a fragment. - -The various scenarios and transitions could be drawn into a pretty diagram if one felt the urge, but hopefully the above -gives sufficient detail on how it's all meant to work. \ No newline at end of file