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

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).

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.

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.

Hashtags

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

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.

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
    

Limitations

At present, the markdown “Editable Text” editor does not offer an easy way to add a link. And adding an image is limited to copying an image that has been added to the paste buffer. To add a link, or to add an image from a file at this time, choose “Markdown Code” in the pulldown menu at the top.

choosing Markdown Code vs. Editable Text while editing an md file

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.