Markdown

Introduction

Wikipedia defines Markdown as “a lightweight markup language for creating formatted text using a plain-text editor” (https://en.wikipedia.org/wiki/Markdown).

Markdown makes it easy to add basic structure, such as headings and lists, to a plaintext document. Use of Markdown is ubiquitous in CoCalc (see below). When you start making notes into a text file, it is often most convenient to open the file as a Markdown document, i.e. a file with name ending in “.md”. It is easy to produce pdf and html files from markdown.

There is a brief tutorial on Markdown in the Project Library. To copy the introduction into a project of yours, open the project and follow the four steps below:

fetching Markdown intro from the project library

The Library intro has three sample files, in format markdown (“.md”), Jupyter notebook (“.ipynb”), and Sage worksheet (“.sagews”). Here’s a view from the .md file:

source and editable views of a .md file

You can find additional information about variations of markdown relevant to CoCalc at the following links:

Where Markdown can be used in CoCalc

Enhanced features in CoCalc Markdown

Checkboxes

Type ” [ ] ” to create an unchecked checkbox. Note the single space between the square brackets. Type ” [x] ” to create a checked box. In both unchecked and checked boxes, there is a space before the first bracket and a space after the closed bracket.

Collaborative editing

Multiple users can edit CoCalc Markdown at the same time. In fact, one user can have several browser windows open to the same Markdown content and edit from them all simultaneously (we sometimes use this feature to test collaboration while developing CoCalc).

Details element

CoCalc markdown editing supports The Details disclosure element. Here is how a details element is entered, using Markdown code edit mode:

<details>
    <summary>summary text</summary>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua...
</details>

You can put text that you want hidden inside the details element. When not expanded, only the summary text is displayed. To expand the content and show the hidden content, click anywhere in the summary. To hide the content, click the summary again. If you do not specify summary text, the word “Details” is used.

a details element with content hidden

details element with content hidden

a details element with content expanded

details element with content expanded

Embedded LaTeX

You can write LaTeX formulas between $ signs, e.g. $\frac{1}{1+x^2}$.

Emojis

View the list of supported emojis in the markdown-it-emojis GitHub repository.

Export to HTML

  • To create html from a markdown file, open a Linux terminal. If your file is “filename.md”, run the command:

    pandoc filename.md -o filename.html
    

Export to PDF

  • To export a markdown (“.md”) file as pdf, open the file, select “Locked” from the view pulldown menu and click the “Print” button.

Hashtags

Precede a word with a hash sign (“#”) and it is formatted to stand out as a hashtag.

About the CoCalc Implementation of Markdown

CoCalc uses markdown-it, with plug-ins and some customizations. Details are in the CoCalc source code at GitHub in file src/packages/frontend/markdown/index.ts.

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:

  • math - math code; 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.

  • emoji - emoji docs; configured with the defaults, so all github supported emojis. 😊

  • checkbox - checkbox code; create checkbox anywhere via [ ] and checked box via [x]. Also supports github task lists.

  • hashtag - hashtag code; create #hashtags anywhere that look like #hashtags. In some parts of cocalc, click on these to search for matches.

  • mentions - mentions code; 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.