How to Read and Organize Paper Using Markdown

9 minute read

Published: October 10, 2023

Introduction

Markdown emerged in 2004, crafted by John Gruber with contributions from Aaron Swartz. It was born from a desire for a plain text format that’s easy to write, read, and convert to HTML. Gruber’s vision was to create a syntax that would look as natural as possible—a document in Markdown is both its source and its display form, making it easily readable without looking like it’s been “marked up” with code. This simplicity has led to widespread adoption, from web writers to enthusiastic software developers, even scholars like me.

:bulb:Fun Facts: Contrastingly, LaTeX is a much older system, dating back to the 1980s. Leslie Lamport developed it as a spin-off of the TeX typesetting system created by Donald Knuth. LaTeX’s strength lies in its precision and power. It’s the go-to choice for many in academia, especially for documents heavy with mathematical notation or when exact control over document layout is required. Its capabilities are vast, but they come with a steeper learning curve, with users needing to familiarize themselves with many commands and environments. Compared to LaTeX, Markdown is undeniably simpler. If you want to know more about the history of Markdown, here is a great blog post.

The beauty of Markdown lies in its simplicity. One can focus solely on the content without the distractions of complex toolbars and formatting menus. Yet, despite this simplicity, Markdown is incredibly versatile. Whether you’re jotting down notes with programming code embedded, drafting a research paper, or writing a book, Markdown is up to the task.

My introduction to Markdown came during an R programming course in 2016. In that course, I became acquainted with R Markdown—a tool that integrates Markdown with R code, allowing for both descriptive content writing and code execution within the same document. Observing this seamless integration of text editing and programming was a revelation. I was particularly impressed when my professor employed R Markdown to craft his course lectures, lab instructions, and even research papers. The experience was mind-blowing.

Yet, at the time, I didn’t fully appreciate the potential of Markdown. After completing the course, it largely faded from my life. Throughout my academic pursuits, I occasionally encountered and edited Markdown files while learning various programming languages, but I never took the initiative to compile one myself. It wasn’t until 2022, as I embarked on redesigning and teaching a course, that memories of my 2016 experience resurfaced. Embracing Markdown once again, I utilized it extensively to create my teaching slides and lab instructions. Furthermore, I published them online by converting them into HTML format.

Nowadays, Markdown files have become an increasingly essential part of my academic routine. Recently, I stumbled upon Mu Li’s vlog (thanks to YouTube’s algorithm), where he mentioned organizing literature using Markdown. While he didn’t provide a detailed blueprint, it inspired me. I decided to start a tutorial blog on how to use Markdown for organizing papers. I believe this approach offers significant advantages, especially for those who don’t want to be constrained by traditional bibliography management software, and create a system of your own document management that is easily portable. The following will be the detailed steps I took.

Setup Working Environment For Markdown Files

There are numerous platforms and software options for editing Markdown files. Your choice largely depends on your specific needs, preferences, and the platform you’re using (Windows, macOS, Linux, or web-based). Since I’m using a MacOS environment, I choose to use Visual Studio Code (VSCode). It supports cross-platform and is a free, open-source code editor with great Markdown support and a live preview feature (instant file complier). There are many extensions available that enhance its Markdown capabilities.

Settting Up VSCode for Markdown

Install VSCode: If you haven’t already, download and install VSCode from their official site.
Install Markdown Extensions: Open VSCode, go to the Extensions view by clicking on the square icon in the sidebar, or press Ctrl/Cmd+Shift+X. Search and install these recommended extensions:
- Markdown All in One: Provides a bunch of handy features like keyboard shortcuts, table of contents, and auto preview.
- Markdown Preview Enhanced: An enhanced Markdown previewer with many features, including Mermaid diagram rendering, MathJax support, and more.
- Markdown Lint: Helps to keep your Markdown files consistent by providing linting (proofreading).

Starting a Markdown File

Create a New File: Open a new file with the .md extension will automatically enable Markdown mode in VSCode.
- Click on the “New File” icon in the top-left corner of the screen (represented by an icon of a sheet of paper with a plus sign). Alternatively, press Ctrl + N (or Cmd + N on macOS) to create a new file.
Change the Language Mode to Markdown: By default, a new file in VSCode might not be recognized as a Markdown file if you do not follow the previous route.
- To explicitly set it: In the bottom-right corner of the VSCode window, you’ll see a language indicator (it might say “Plain Text” or another language, depending on your settings).
- Click on the language indicator. In the search bar that appears at the top, type “Markdown” and select it from the dropdown list.
Save the File: Before you start writing, saving the file is a good practice. It ensures that any settings or extensions specific to Markdown will be correctly applied.
- Simply press Ctrl + S (or Cmd + S on macOS). Choose a location on your computer where you’d like to save the file.
- Give it a name with the .md or .markdown extension (e.g., xxx.md). Click “Save.”
Start Writing in Markdown: Now, you’re ready to start writing in Markdown!

Start Writing in Markdown

Now, you’re ready to start writing in Markdown! Here’s a brief primer on some basic Markdown syntax to get you started:

Headers:

# This is a level 1 header
## This is a level 2 header
### This is a level 3 header

Lists:

- Item 1
- Item 2
  - Sub-item 1
  - Sub-item 2

Links:

[Google](https://www.google.com)

Images:

![Alt text](URL_to_image)

Bold and Italic:

**This is bold text**
*This is italic text*

Preview Your Markdown

To view the rendered Markdown, Click the “Open Preview to the Side” option by right-clicking your mouse anywhere in your Markdown editor. Or use the shortcut Cmd + Shift + V (on macOS) or Ctrl + Shift + V (on Windows/Linux) to toggle the Markdown preview. It will open a live preview of your Markdown file, showing you how it will look when rendered.

Remember, Markdown is designed to be easy to write and read, so the syntax is intuitive. As you continue to use it, you’ll become more familiar with its features and capabilities. There are tons of resources online for Markdown syntax. You can always Google them yourself.

Organize Your Academic Literature

Start a Template

When it comes to using Markdown to organize your academic papers, it depends on your preference and practice. Remember, the key to efficient note-taking is consistency. Find a style and structure that suits you and stick with it. Over time, you’ll amass a valuable database of insights from various papers, all neatly organized and easily accessible!

This is a general template I use:

Organize by Topics or Themes: Use headers to organize your literature by topics or themes. Categorization using Tags: You can add tags to easily categorize and filter through your notes.
```
  ## The Economics of Density

  Tags: #CGE Model #Remote Working
    
```

Literature Metadata: Start each entry with the essential metadata of the literature.

  Ahlfeldt, G.M., Redding, S.J., Sturm, D.M. and Wolf, N. (2015), The Economics of Density: Evidence From the Berlin Wall. Econometrica, 83: 2127-2189. [Paper Online Link;](https://doi.org/10.3982/ECTA10876) [PDF](path/to/local/file)

  **Keywords**: 
  **Abstract**:
  **Number Cited**: 

Notes and Summaries: Beneath the metadata, write your notes, summaries, and important quotes.
```
  ### Notes: 
  ### Quotes: 
  > "........."
```
Embed Images or Diagrams: If a paper has an important figure or diagram, you can embed it directly into your markdown file.
```
  ![Figure 1: Architecture of the proposed model](path/to/image.png)
```

You can also use check lists or tables to plan your tasks and organize your literature reviews.

  To-Read:
      - [ ] Smith, A. (2021). Advanced Markdown Techniques.
      - [x] Lee, K. (2020). The Rise of Lightweight Markup.

      | Author       | Year | Key Findings                  |
      |--------------|------|-------------------------------|
      | Doe, J.     | 2020 | Importance of Markdown        |
      | Smith, A.   | 2021 | Advanced Markdown Techniques  |

Use Mermaid Diagrams: With “Markdown Preview Enhanced”, you can also embed Mermaid diagrams directly in your notes.

Organizing and Version Control

Folders and Files: Consider creating a dedicated folder for your academic notes within which you can have sub-folders based on topics, conferences, or any other categorization scheme. Use the VSCode Explorer (Ctrl+Shift+E) to navigate through these.

Use Workspaces: If you’re working on multiple projects or have different sets of papers, you might want to consider using the “Workspaces” feature in VSCode. This allows you to have different editor settings and extensions for different projects.

Version Control with Git: VSCode has built-in Git integration. You can initialize a Git repository in your notes directory, allowing you to track changes, save versions, and even sync with online platforms like GitHub or GitLab.

Share on

Twitter Facebook LinkedIn

Xiaozhong Sun