Five use-cases for using Markdown Editors for Long-form Academic Document Composition

Five use-cases for using Markdown Editors in Long-form Academic Document Composition

What are markdown editors?

If you are looking for a way to write faster, easier and better, you might want to consider using a markdown editor. A markdown editor is a software that lets you write in plain text and apply formatting with simple symbols. For example, you can use asterisks to make text bold or italic, or use hashtags to create headings. You can write and format your text in the editor mode, and then preview the final result in the preview mode.

There are dedicated markdown editors such as obsidian and typora which are largely used by creative and technical writers with minimal software programming background. However, some integrated development environment (IDE) like RStudio and visual studio are used as markdown editors particularly among technical writers with software programming background for code and software documentation. Most markdown formatting will work across most markdown editors however some markdown formatting are unique to the specific editors.

Markdown editors are different from the traditional word processors that most of us are familiar with, such as Microsoft Word. These word processors are based on the principle of “what you see is what you get” (WYSIWYG), which means that you see the formatting as you type. However, this can also be distracting and cumbersome, especially when you are working on long and complex documents.

In this blog post, I will give a 5 use-cases where markdown editors can help you write better long form academic documents.

1. Increased productivity through simplified formatting

Like most graduate students, i was well-acquainted with the ubiquitous Microsoft Word. While Word offers familiarity, accessibility through university accounts, and a range of features, it can be burdensome when it comes to formatting long documents. For instance:

• Inserting or updating images or tables often necessitates manual adjustments in Word, including resizing and spacing corrections to maintain the document’s visual harmony.
• Copying and pasting text from various sources into Word frequently carries over formatting inconsistencies, leading to formatting discrepancies in the final document.

These challenges are undoubtedly familiar to anyone who has undertaken long-form writing projects. Please share your experiences or other similar examples in the comments below.

In contrast, Markdown-based tools offer an elegant solution. A simple line of code effortlessly maintains formatting consistency, regardless of the number of revisions. Markdown editors automatically update figure numbers when images are added, and all pasted text is stripped of extraneous formatting. Sub-chapters can be seamlessly reorganized, added, or removed, with automatic chapter numbering of the final document. Markdown editors empowers writers to focus their precious time on the actual writing, sparing them the drudgery of managing formatting intricacies.

(a) Markdown formatted document

(b) PDF printout of document

Figure 1: This is an example of automatic numbering of chapter headings and figure captions within markdown

2. Seamless Integration of Publication-Ready Images

Conventional word processors often fall short when handling images generated from data analysis tools. These images at times may appear blurry, exhibit poor color contrast, or present image text in smaller fonts. Flow charts and schematic diagrams can be particularly troublesome, as they tend to shift or lose elements particularly when document containing them are shared among collaborators or supervisors. Let me know in the comments section if anything like this has ever happened to you.

RStudio, a powerful data visualization tool and markdown editor, offers an elegant solution. The tool allows authors to draft text alongside the code that generates images, facilitating real-time image adjustments within the markdown environment.

While creating flow charts and schematic diagrams in a traditional word processor may be straightforward, markdown editors typically incorporate tools like mermaid.js, that reduces time spent in creating and editing complex flow charts with plain text. This approach, though requiring some familiarity with mermaid syntax, streamlines the creation of intricate flow charts in a matter of minutes.

library(DiagrammeR)


mermaid("graph LR
  subgraph Preparation
  A((Start))--> B(Step 1)
  end
  subgraph Execution
  B --> C{Step 2}
  C --> D(Step 3)
  E(Step 4) --> F(Step 5)
  end
  subgraph Conclusion
  C --> G(Step 6)
  F--> H[Step 7]
  end")

Figure 2: This is an example of a flow digram generated in RStudio using the code chuck above. This also illustrates how data analysis outputs can be easily inserted within writeup and updated within the same environment as your writeup.

3. Enhanced Reproducibility

Data analysis and writing are iterative processes, often involving multiple rounds of revising and refining data and writing outputs. When it comes to data analysis, additional data may become available after initial data analysis and report drafting, which may necessitate reanalysis of data or even new analysis. Managing these evolving datasets can be complex and error-prone, especially when managing different data files over time while not having good data management practices.

In addition, during long-form writing, numerous unformed ideas can be captured as notes within earlier document drafts which might require revisions or supporting evidence. The conventional method to manage these unformed ideas is to color-highlight these text and editing them later or deleting them (Figure 3 (c)). If you employ other methods for managing unformed ideas, please share in the comments section.

(a) commenting in RStudio. The dark blue text is commented out using html commenting syntax and will be absent in the printed or rendered final document

(b) Commenting in obsidian. Obsidian is a popular note-taking markdown editor that uses html as well as obsidian flavored markdown comment syntax. Obsidian flavored markdown comments might be visible in some rendered output formats

(c) Commenting in Word. The text containing the unformed ideas is highlighted with yellow highlight and a comment added to reference action to be taken

Figure 3: Different ways to comment out unformed ideas within long-form write-ups

However, deleting or editing these unformed ideas might leave you in a situation where you might need these ideas at a later date. An alternative way to managing this using markdown editors is to comment out these unformed ideas within your writing. This allows you to refer to them during later revisions however not have them visible within your printed or rendered document.

Another alternative is to use version control. Markdown editors, when coupled with Git and GitHub for version control, offer a powerful solution for tracking document changes. This approach allows you to have all your data analysis and writing consolidated within a single location and have historical versions of the document preserved for reference. With Git’s version control capabilities, authors can effectively manage evolving data and track changes across different document drafts.

4. Chapter referencing

Word while compatible with citation managers like Mendeley or Zotero, it can encounter challenges when inserting chapter-specific references at the end of each chapter within a long-form document. To facilitate insertion of references at the end of each chapter, authors often resort to creating separate chapter documents, risking citation duplications.

Markdown editors can circumvent this issue through using specific YAML code. The code instructs the editor to aggregate all the references cited within the specific chapter at the end of the chapter. This approach eliminates the risk of duplicated references within a single document, providing a cleaner and more accurate reference list.

5. Document repurposing and LaTeX Support

Markdown editors offer effortless file conversion of a single document into various document formats using pandoc file conversion. Authors can generate research grant reports, presentations, books, or manuscripts from the same source file with minimal adjustments. This approach saves time and ensures uniformity in message communicated.

Additionally, markdown editors often incorporate pandoc plugins and MathJax, to simplify the inclusion of mathematical formulas and equations. Beautifully typeset LaTeX documents can be easily generated while retaining mathematical formatting via pandoc conversion with the assistance of packages like TinyTex or programs like MikTeX. This feature is particularly beneficial for researchers with scientific backgrounds that frequently use mathematical symbols and equations as part of their regular write-up.

EXAMPLE 1

This \(Persons \; infected = \frac{(\frac{RNA \; copies}{liter \; wastewater})* (\frac{liter \; wastewater}{days})}{(\frac{g \; feces}{person-day})*(\frac{RNA \; copies}{g \; feces})}\)¹ is an example of an equation written within a sentence.

This \[Persons \; infected = \frac{(\frac{RNA \; copies}{liter \; wastewater})* (\frac{liter \; wastewater}{days})}{(\frac{g \; feces}{person-day})*(\frac{RNA \; copies}{g \; feces})}\] is the same equation written between paragraphs.

   # Syntax for above equation

  Persons \; infected = \frac{(\frac{RNA \; copies}{liter \; wastewater})*     (\frac{liter \; wastewater}{days})}{(\frac{g \;feces}{person-day})*(\frac{RNA \; copies}{g \; feces})}

EXAMPLE 2

This \(L_T(\vec{\lambda})=\sum_{(x,s)}\log P{(s|x)}-\sum_{i=1}^m\frac{\lambda_i^2}{2\sigma^2}\) is an example of a mathematical equation written within a sentence.

This \[L_T(\vec{\lambda})=\sum_{(x,s)}\log P{(s|x)}-\sum_{i=1}^m \frac{\lambda_i^2}{2\sigma^2}\] is the same equation written between paragraphs.

 # Syntax for above equation

  L_T(\vec{\lambda})=\sum_{(x,s)}\log P{(s|x)}-\sum_{i=1}^m\frac{\lambda_i^2}{2\sigma^2}

Final thoughts

This blog highlights why markdown editors can be an appealing alternative for long form academic writing. As a matter of fact, I wrote my PhD thesis using RMarkdown after a number of frustrating experiences i had with using and experimenting with WYSIWYG editors. The advantages of markdown-editors mentioned in this blog, extend beyond drafting dissertations. Markdown editors, like RStudio and Obsidian, offer versatile solutions for most forms of report and document drafting.

Was this interesting?

Please share your related writing challenges and experiences with markdown editors within the comments section below or in the top right hypothes.is sidebar.

If you found this blog informative, kindly share it with friends and colleagues through your favorite social media platforms using the sharing options conveniently located on this page.

If you have specific academic writing challenges using Rstudio or obsidian, feel free to reach out at Discord

If you would like to read more on this, Quarto - Creating a Book

Figure 1 (a): Markdown formatted document Figure 1 (b): PDF printout of document Figure 3 (a): commenting in RStudio. The dark blue text is commented out using html commenting syntax and will be absent in the printed or rendered final document Figure 3 (b): Commenting in obsidian. Obsidian is a popular note-taking markdown editor that uses html as well as obsidian flavored markdown comment syntax. Obsidian flavored markdown comments might be visible in some rendered output formats Figure 3 (c): Commenting in Word. The text containing the unformed ideas is highlighted with yellow highlight and a comment added to reference action to be taken

Footnotes

1. Ahmed, W. et al. (2020) ‘First confirmed detection of SARS-CoV-2 in untreated wastewater in Australia: A proof of concept for the wastewater surveillance of COVID-19 in the community’, The Science of the Total Environment, 728, p. 138764. Available at: https://doi.org/10.1016/j.scitotenv.2020.138764