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.

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.