How to use Overleaf to Write your papers: Part III: How to use Markdown with Overleaf with help from Git and Pandoc

You can easily use Markdown in a Plain Text Writing App and update a neatly formatted Overleaf document with all its bells and whistles. Here’s how.

Part I of this Series
Part II of this Series

It’s great to be able to write in LaTeX and use Overleaf. Basically, all you have to do is to write in LaTex anywhere and just upload the tex file to Overleaf. Or you can also use the Wysiwyg editor in Overleaf to add content. However, there is another way: using Markdown in a plain text editor and build up Overleaf and push everywhere through Overleaf.

Markdown was designed by John Gruber in 2004. It is a great way to write clean, styled document using only plain text and nothing more. The structure of writing Markdown documents is highly standardised, and very intuitive. A Markdown document is also very clean to read and share with people who do not know anything about Markdown at all. You should be able to edit Markdown documents in any text editor (but avoid, if you can MS Word or Google Docs, or OpenOffice or LibreOffice), any office doc system is not the best tool. You can use a notepad to write in markdown. There are excellent web based tools to write markdown as well. Learn more about Markdown here:

You can use Markdown to write your document and use Overleaf to produce a neat stylised PDF document at the same time (see the header image of this article). This has several advantages. First, Markdown is dead simple to use; practically nothing to learn yet you can use all the benefits of using Overleaf without knowing practically anything about how to write LaTeX. Second, as Markdown is a plain text based system, you can use it everywhere exactly like you can use Overleaf in every device. Third, there are scores of Apps, several of them free that will let you use Markdown and write in nice stylised markdown and produce beautiful document. I’d encourage you to use Markdown to write your paper and publish using Overleaf in real time.

Why would you like to use Markdown with Overleaf?

It is the best of both worlds. Markdown is easy to write. It is based on plain text. You can give your copy of Markdown formatted document to anyone for editing, without any fuss about the structure that a LaTeX code embedded document is likely to incur. People who only use Word/wordprocessors and nothing else, or would not like to use Overleaf or fussy about other applications, will not have any problem about opening Markdown formatted documents (just provide them with an extension of .txt). You can open such a document in any text processing applications. Plus it is great for processing to appear in Web pages, so you write once in Markdown and purpose it for slides, papers, PDFs, whatever. Here, I am going to show you you can use it to work with Overleaf as well without knowing LaTeX. Here’s the hack. Essentially very simple once you play with it, but the first time will look like quite a bit of work to get started. These are all one time set up.

In order to get it work, you will need a bit of set up (and I have provided you the codes, etc, to get you going). Later in the series, I will show you how I use a code editor (Sublime-Edit) to write Markdown and publish through Overleaf. Here’s a Markdown cheat sheet to get you started:

For now, let’s get the basics sorted.

Step I: Install some apps to get started:

  • Install Pandoc (a free, open-source app) on your machine. Get Pandoc from here:
  • Install Git (a free, version control system that also interfaces with Overleaf). Get Git from here:
  • Start with Overleaf. This is important. In Overleaf, create your new project and give it a name. Fill in the details. Then, head over to main.tex file and add the following code at the preamble:
\documentclass[a4paper]{article}
\usepackage[english]{babel}
\usepackage[utf8x]{inputenc}
\usepackage{amsmath}
\usepackage{graphicx}
\usepackage[colorinlistoftodos]{todonotes}\usepackage{booktabs}
\usepackage{hyperref}
\usepackage{enumitem}
\usepackage{longtable}
\setlist{nosep, noitemsep}
\providecommand{\tightlist}{%
\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}\title{Write your Title}
\author{Your Name \\ Other Information}
\date{\today}
\begin{document}
\maketitle
\include{background}
\bibliography{references}
\bibliographystyle{plain}
\end{document}

Step II: Clone the document from Overleaf to a folder and git it

In order to do this, you will need to know a little bit of Git. Git is a version control system and you can learn about working your way with Git from the following resource:

I suggest you work your way through the tutorial.

Here are the steps to get the git going with Overleaf:

  1. Visit the Overleaf project. See where it says “share” and open that window. In that page, you will find a box “Clone with Git”
  2. Make the changes in the main.tex file
  3. Create a folder where you will store your local files
  4. Then, open a terminal (I assume you have Git and Pandoc installed and properly configured) and type:
git clone <url of the share>

The Git app on your computer will work and put the contents of the Overleaf folder of your project there. You have now created a Git repository (note that it will have a name that similar to the project name of your Overleaf (a name that looks like a code given to it by Overleaf, not the name or title you gave it). This new folder which is now connected to your Overleaf account through git is referred to as Repository. You will add and modify this to talk to Overleaf and work from here. Change into this directory by typing

cd <the name of the repository>

Now, here, you are going to work with Markdown files on your device (that device can be your desktop computer, notebook/laptop/phone/iPad/Tablet, whatever). The filename extension for markdown documents is .md, but as it happens, Overleaf file space does not allow you to upload filenames with extensions such as .md. If you do not have a plan to exclude .md files being transported from your Git repository to the repository at Overleaf, your plan is not going to work. Hence, you will need to create what is known as a .gitignore file and indicate that you will keep all files with .md in them and push them to gitignore so that they will not be transferred to Overleaf. Here is the manual for gitignore, and I recommend you read it:

In Mac for instance, in your directory, you create a .gitignore file by doing:

touch .gitignore

Then, in this gitignore file, in each line, you type the name of the file or pattern that you want Git to ignore while staging changes and then uploading to your Overleaf repository. In our example, we would like to ignore .md files (some people and app use .markdown for markdown files, so it may be a good idea to add .markdown as well). So, you do as follows:

echo *.md > .gitignore

Now that you have created a file .gitignore and added .md to it, you will need to push the .gitignore to the Overleaf repository. For this, write the following code at the command prompt:

git add .

This is going to add .gitignore to the cue that it will be sent to the Overleaf repository. As you have also changed the local repository (this is called “staging”), you will now need to write a message (this is called commit). Write a commit message,

git commit -m ‘added gitignore’

Now you have to send the file to the Overleaf repository, so do that by executing the following:

git push

We shall later see that this is part of a process. Let’s turn to do the next bit, which is using Pandoc. I assume that by now you have already installed Pandoc on your machine. To check that pandoc is installed, do:

pandoc —-version

If you have pandoc installed, it will show you the version information and other details. If not, you have to visit the Pandoc site, and install it for your system.

Step III: Write a Markdown document

Now is the time to write a markdown document. Remember that in our work, we are going to use two levels of headers (as Overleaf’s wysiwyg writing environment allows you two levels; we can include enumerated lists, and bullet point lists; as we are writing a scholarly document, we should ideally include tables, figures, and citations drawn from a bibtex formatted bibliographic reference list. In our case that bibtex formatted bibliographic reference list is reference.bib that we have downloaded via git from Overleaf. With these constraints you can write a document in markdown that looks somewhat like this:

# A Sample Markdown Document
## This is a second level header
The objective here is to write a simple document with some components we come to accept in a scholarly document. OK, so here is how we should write:
- This is the first element of a bullet point list
- This is the second element of a bullet point list
1. This is the first element of a numbered list
2. This is the second element of a numbered list

Writing a table is simple too, just as follows
 | Header Element  | Second Column Header  |
| — — — — — — — — | — — — — — — — — — — — |
| First cell | Second Cell |
| More info | More more info |
You can see how easy it is to create tables directly here. You can of course use Tablesgenerator generated tables too, and in that site, you will find tables to generate from csv files for markdown formatted tables. Use them. 
Finally, if you want to add citations, you need to add citation ID that you will find in your references.bib file. For instance, I have put the citation 

This is an article that discusses a markdown processor referred to as madoko. If you have not checked it out yet, you should. This article was written by Dan Leijen (2015) and discussed the implementation of Madoko cite{leijen2015}

There are different ways to add citation usually adding an at sign and then the citation and letting Pandoc to process citations, but here, since we have specified our bibligraphy file and we’d rather like that Overleaf will process our citations, we just simplify the citation addition like this. This may mean that we will need to tidy the citations by hand in the resulting document. YOu can also bypass by using cite{citation ID} but keeping it as a code or with an escape element.
@article{leijen2015,
title={Madoko: Scholarly markdown in the cloud},
author={Leijen, Daan},
journal={SNAPL’15: The Inaugural Summit on Advances in Programming Languages},
year={2015}
}




Step IV: Process this document with Pandoc

Let’s say we saved the document as first.md. We are going to ask Pandoc to do the following:

  1. We shall provide the name of the document we want to change from Markdown to LaTeX, so we shall say pandoc first.md
  2. Then we ask Pandoc to convert it from markdown to latex, so we say pandoc first.md -f markdown -t latex
  3. As we also have added citations we need to tell markdown to find the citations from our references.bib file so we also need to tell Pandoc that
  4. Finally, we want Pandoc to output a latex document which will end with a tex extension and we decide to name it first.tex. Note that at this stage if we are only going to write a part of my paper I won’t need a standalone document. At other times, we will need to output a standalone document. If you do, add -s to the mix.

So, the code looks like this:

pandoc first.md -f markdown -t latex -o first.tex

If you copy and paste the above code and run in the folder from a command prompt, Pandoc will run the code. If everything goes correctly, then pandoc will return no error message. You can check that your new file first.tex exists by typing ls at the command prompt and see that it exists in the folder. Next, if you want this file to be added to the main.tex for Overleaf to process, just make a small change to your main.tex file and include the file with

\include{first}

Note, do not add the tex extension to it. That’s it.

Step V: Use git and sync the files

Now that you have done the following:

  • Created a first.tex file
  • Added an entry to the References list
  • Modified the main.tex to add this file

You are ready to push these changes to the Overleaf server. So what you want to do is:

git status
git add .
git commit -m -a ‘added first, changed files’
git push

Step VI: Open Overleaf site and see the changes take effect

You can see in the first pass, it is not really perfect, and you will need to make changes. In particular, you need to make changes to the citations, etc. You can do that now directly on the Overleaf site, or you can work some more on your markdown document to tidy it further and continue to push the changes. The choice is really yours. I usually tidy up the references the last thing after I am satisfied with all my references. Some elements such as insertions of figures, and correcting the nesting of lists, etc can be easily done from the base markdown document and work. So the next thing you want to do is to change things in Overleaf, and then bring those changes back to your computer or to the Markdown editor where you are working and push those changes if you need.

In order to do that, all you need to do is as follows:

git pull
git status
git add .
git commit -m -a ‘Your message goes in here’
git push

Note:

  1. The first line will now pull in the changes from your Overleaf document space
  2. You may additionally want to convert the tex file that you pulled in to your document space and work there. Note that if you use pandoc, it will not give you back the LaTeX tables to the neat format you used for writing in your markdown document, so be a little tactful about what to do.
  3. Then continue to work on your markdown formatted or tex formatted files and add and push.

This way you keep working on your markdown document either on the desktop or on the web, and as you play with git and pandoc, your document gets pushed to Overleaf in a tidy format. You can of course modify and continue to work in Overleaf as well, and pull in the changes when you need to work on them more.

Summary

So the workflow goes like this:

  1. Start a document with Overleaf.
  2. Use git to sync that document with a folder of your choice on your desktop
  3. If the Overleaf document already has some text based tex codes written (not too much tables, etc), then convert the tex document using Pandoc to markdown and work on it.
  4. Use Pandoc again to convert the Markdown formatted document to LaTeX and use git to upload back to Overleaf.
  5. Let Overleaf compile the tex and you can make changes

In the next part, I will write about how I have configured code editors to write in Markdown and watch changes occur in Overleaf with these hacks.