How to write a paper using myst markdown

Abstract

Write an abstract as the first human readable element of the paper. 
Separate the title of the abstract from the rest of the body or a heading from the rest of the body using a blank line.
One line per line is fine.
The abstract is unformatted.
In this paper we are describing how to write a paper using myst markdown.

Introduction¶

Myst markdown or Curvenote markdown enables you to use markdown and jupyter notebooks together to weave codes, figures, and data to tell a data-driven narrative, but you can also use it as plain markdown to write a story in different formats.

How to get started with myst-markdown¶

You can install myst markdown for your operating system with the following code (assuming you have first installed node and npm)

npm install -g myst-cli

You can also alternatively use npm install -g curvenote and in that case you will use curvenote instead of myst.

Then, in a folder create the following two files:

• A markdown file and give it a name like foo.md
• A jupyter notebook file and give it a name like foo.ipynb
• Optionally, if you use bibtex for your reference management, then add a bibtex file in the same folder with something like foo.bib.
• You can keep your figures in the same folder or in a subfolder in the same folder if you like
• After this, test that everything works with myst init at the command prompt
• When myst init finishes, it will ask you if you want to start a server, respond yes or Y. It will start a server at localhost:3000. If you cannot open localhost:3000 on your browser, open something like https://127.0.0.1:3000 or something similar. You will see a webpage that is pretty much empty or blank, and that is fine. You are now ready to work on the pages.

Then write your content in the markdown file using markdown. You can use academic markdown or jupyter flavoured markdown if you like. At the beginning of the markdown file, start with a frontmatter block with something like follows:

---
title: Title of your paper
authors:
  - name: Your name
  - email: your email
  - affiliation: your affiliation, etc
bibliography: foo.bib
---

I recommend that this is a bare minimum to get started with a myst-markdown file. Consult the myst webpage to learn more about formatting your paper. This will let you create a webpage. If you want to export your file to word, then add an export: docx line to the frontmatter.

You generally use a jupyter notebook for generating figures and tables, and use the markdown to write the narrative. Conventionally, we know writing any academic or scholarly document requires the writer to provide the following structure (this can vary but generally this is true of most structures):

• An Abstract
• An Introduction or the background
• A section on methods etc
• A set of results if that is applicable
• A discussion section
• Tables
• Figures
• Citations throughout the paper
• A list of references at the end of the paper appended to it

How to convert a list to a table¶

The above list in myst markdown can be conveniently converted to a table Let's copy paste and add what we want by way of describing each one.

This list table now becomes table one if you want to refer to it as Table 1 where the name of the table is what you write within a pair of parentheses after a pair of square brackets.

Summary: how to add tables¶

So, the above process is one way to add a table. Another way to add a table is to use a list table or use a markdown table.

• Add tables as list tables
• Convert a list to a table
• Use a markdown table as a list table

Cross-reference a table¶

If you want to cross-reference a table, use [](#table_name). Doing this will produce a highlighted table number that will be automatically updated. Example: As seen in Table 2, this is a thing blah blah.

We can also write a markdown table and then use it as a list table.

In this case Table 3 is a list table

How to add figures and images¶

I can refer to the image as Figure 1

I could also save this image of the cat to the local folder where I have the paper and then replace the rest of the url with ./, it would have the same effect. Later on in this document I will write how you can intereface a jupyter notebook with all these elements with cross-referencing, but for now pretend we are writing using nothing but markdown syntax.

How to add Citations and table of references¶

Citations are important and there are a few ways to insert citations in myst markdown formatted papers. The easiest way is to locate the DOI of the paper say from crossref.org and insert the DOI. Like this [](doi url) will produce something like as follows: a statement by Fenner, 2013 if it is a valid DOI, it will parse the DOI, add a citation and add a reference item when it produces the formatted page.

A second method of producing the same content using the DOI and nothing else is to use Fenner, 2013 ; this will also produce something similar. In this case start with cite code and then add the doi: doi next to it.

A third method, if you do not have a valid DOI, is to use a bibtex file and then do as follows:

1. First add the bibtex file to the frontmatter
2. Then add the reference to the bibtex file
3. Then source the bibtext file id in the text of the paper

The following citation was posted this way. White has written an article on how to write scholarly documents (White, 2022 ). There are other ways of writing this as well, such as White (2022) has proposed ways of writing scholarly document and so on. The idea here is you put together a bibtex file, add it to the folder where you keep your markdown file and then when you want to cite it, use this syntax of {cite} followed by doi written between backticks. The doi could be raw doi taken off from crossref or from anywhere or you can use the citation id of the citation that you want to add to your paper.

Interface with Jupyter Notebook¶

Working with Jupyter notebooks in the same folder, it is possible to add any table, figure or code from a cell in the notebook to the markdown document and output it. This keeps the analyses clean and focused and the content authoring under control. This is really helpful if you have to work with multiple authors who need to read the outputs and tables and figures and where necessary, if anyone want to review the codes, they can be shared as well with the raw ipynb file. Here are the steps:

1. Start every code block with #| label: xxx where xxx is whatever label you want to assign to that code block
2. Generate a table or a figure as an output
3. Work with Julia, using prettytable package, output the table as a markdown table
4. If you work with R or Python, use knitr or another package to output the table as markdown table
5. In the main body, you can either directly cross-refence that table with ![](#label of the code block) or copy paste from the notebook. Note here the use of the bang sign.
6. You do something similar with figures. You can either directly show cross-reference with ![](#label) or save the figure as a png or jpg and show them directly as you do with figures.

How to output results of a table from ipynb¶

      x       y 
  Int64   Int64 

      1       6
      2       7
      3       8
      4       9
      5      10

If you take a look at this above table, it is a raw table from jupyter, not as fun. This can be made useful depending on your use case but there are some other ways. You can embed this notebook output as a list table

      x       y 
  Int64   Int64 

      1       6
      2       7
      3       8
      4       9
      5      10

Still not good and and basically same as above, Worst, it seems embedded.

How about copying and pasting and then modifying the table?

A little bit of work in the sense you will need to line up the rows but the results are much prettier if you output as markdown table.

Something similar happens if you want to output a figure. In this case, do something like as follows:

How to output the paper to a website or a Word Document¶

When you work with a code editor to write a paper like this, it will print out the outputs to a temporary webpage that you can see. If you want to output them to an html file, do