Markdown Module
A small markdown renderer for Issie's in-app help. Issie's longer help text - the Info window, the waveform simulator's help panels, the bodies of confirmation popups - used to be written as React element trees: `str` and `bSpan` and `li` interleaved with the words, several hundred lines of it. Read as prose it was unreadable, which is a problem for text whose whole job is to read well. It is now written as markdown in AppMessages and rendered here. The subset is not a guess: it is what that text was already doing, counted. Headings, bold, italic, inline code, links, bullet and numbered lists, and tables - which is core GitHub markdown with nothing left over. There are no images and no nested lists, so there is no support for them; a line that tries will render as its own text rather than silently vanish. One addition to that subset: [[Ctrl 0]] draws the keys of a chord as keys. Help text that tells the reader to press something should say it the way the rest of Issie does, and bold prose in the middle of a sentence is not that. TWO THINGS THIS DELIBERATELY DOES NOT DO. It does not produce an HTML string. Rendering markdown by handing HTML to `dangerouslySetInnerHTML` is the usual shortcut, and in a renderer with node integration, for messages that interpolate sheet names the user chose, it is a bad trade. `render` builds React elements, so there is no path from message text to executed markup. It does not open links itself. A markdown link becomes an anchor with an `onClick` supplied by the caller, because in Electron an ordinary `href` navigates the application window away from Issie. Keeping the handler out here also keeps this module free of Electron and of anything above it in compile order. `parse` is pure and returns data, so the tests can read every message in AppMessages under plain .NET without a browser. `render` is the only part that needs one.
Types
| Type | Description |
Functions and values
| Function or value | Description |
|
|
|
Split a line into text and emphasis. Written as a scan rather than with a regular expression per mark so that the marks cannot interleave wrongly: at each position at most one of them can start, and each runs to its own closing mark. An unclosed mark is not an error - it is left as literal text, which is what a reader of the source would expect and what stops one stray asterisk swallowing a paragraph.
|
Full Usage:
render onLink text
Parameters:
string -> unit
text : string
Returns: ReactElement
|
|
Full Usage:
renderBlocks onLink blocks
Parameters:
string -> unit
blocks : Block list
Returns: ReactElement
|
|
Full Usage:
renderInlines onLink inlines
Parameters:
string -> unit
inlines : Inline list
Returns: ReactElement list
|