Markdown help in Markdown file

[kcrisman]

Several file types in CoCalc have lovely help buttons. But there isn't a link to any markdown syntax help in the markdown files themselves (though there is, say, Sage worksheets). Could be useful for beginners - or those who forgot some incantation and don't want to do a web search for possibly a different flavor of markdown than that which CoCalc uses.

[mforbes]

It would also be useful to have a "show me how" video or similar pointing out all of the new features (in edit mode esp.) like adding hyperlinks. (The regular docs also need updating since now links can be added).

[williamstein]

@DrXyzzy will likely add these docs. To make it easier, here is a quick and hopefully definitive summary of what the status is right now, based on me looking at the latest version of the source code (see https://cocalc.com/github/sagemathinc/cocalc/tree/master/src/packages/frontend/markdown).

CoCalc markdown is parsed using markdown-it with the linkify and html options set to true, so that patterns that look like URL's are clickable and html blocks and fragments are parsed as html, according to the commonmark spec (which can be weird, subtle, and surprising!). CoCalc's markdown is also parsed with the following five plugins enabled. Except for the emoji plugin, these are all forks of upstreams plugins:

1. math - code here; this is a proper markdown-it plugin with rules designed to be as close to Jupyter classic's math formula parsing as I could write. By default math is rendered using katex by default, then mathjax if that fails. There are also some hacks to extend katex support.
2. emoji - docs here; configured with the defaults, so all github supported emojis. :blush:
3. checkbox - code here; create checkbox anywhere via [ ] and checked box via [x]. Also supports github task lists.
4. hashtag - code here; create #hashtags anywhere that look like #hashtags. In some parts of cocalc, click on these to search for matches.
5. mentions - code here; type @ then select the name of one of your collaborators. They will receive an email pointing to your mention of them. For chat, the rest of the line is included as context in the @mention.

CoCalc's markdown is only parsed using markdown-it. It is rendered using a custom React-based renderer that is built around slatejs, which we also use for direct rich text editing of markdown. Thus rendering is much more rigid and structured than most markdown renderers, which simply export an html string and let the browser interpret it. For example, rendering of code blocks (triple back ticks) is accomplished using CodeMirror's parser and react to provide syntax highlighting for any mode we support. The html blocks are rendered using html-react-parser, so they will only work if they are valid complete html; moreover, in context like the share server or untrusted notebooks, where the HTML shouldn't be trusted, our markdown renderer sanitizes the html using the xss module.

[DrXyzzy]

I added the information posted by @williamstein above to the docs at https://doc.cocalc.com/markdown.html#about-the-cocalc-implementation-of-markdown

I also added a section on reference links to the feature set of markdown editing: https://doc.cocalc.com/markdown.html#reference-links

[williamstein]

All (non-deprecated) file editors now have drop down menus and these all have a Help menu with some links.