Biochemistry Computational Research Facility (BCRF)

Do yourself a favor: learn Markdown – Episode 3, Academic writing

Posted on

Markdown Academic Writing

Academic writing with Markdown

The origin of Markdown was a simple editing process to export web pages in HTML. In Episode 1 we learned that (original) Markdown has a simple syntax for enhancing text with rich elements while retaining the readability of a plain text format. Episode 2 explored Markdown variants and Markdown (free) software.

In this Episode we’ll discover how Markdown can help with Academic writing. Please note that the methods described here may require a little more work beyond Markdown.

Authorship with Markdown

Writing with Markdown and exporting documents in various formats is taking advantage of the simple Markdown syntax and the (free) software detailed in the previous episode, even including mathematical formulas. However, fancier methods are needed for a closer control of the final exported content format within the final documents such as those useful for scientific writing.

Software others are using

Various software methods are available for this purpose that are open source usually available on all computer platforms and do not rely on commercial software. The software listed below is used to produce great quality, scientific PDF files but the process can be rendered easier with Markdown

Pandoc – a universal document converter

If you need to convert files from one markup format into another, pandoc is your swiss-army knife. (pandoc web site.)

Pandoc is a command-line software so it may not appeal to everyone in spite of its power.

LaTeX – A document preparation system

LaTeX is a high-quality typesetting system; it includes features designed for the production of technical and scientific documentation. LaTeX is the de facto standard for the communication and publication of scientific documents. LaTeX is available as free software.

LaTeX (pronounced Lay-Tek) provides detailed precision to control the final format but its syntax is complex.

These 2 software are actively used and the following blogs or tutorials are highlighting further their use.

Rmarktown in RStudio

This is the method that I use most of the time to create documents. While this is related to the programming software R documents can be created without using R itself, just the amazing RStudio can can be installed on top of it. The pandoc software exists as an R package called “pander” and all other ancillary software as well starting with markdown which has been augmented for use within R and is called Rmarkdown. The definitive guide is available online: R Markdown Book.

One main use of this method is to create reports for “reproducible research.”
See my tutorials  R / RStudio: creating reports for “reproducible research”

Bookdown and Blogdown

The newest development for using Rmarkdown are the R packages Bookdown and Blogdown that allow the writing of books and web sites. Books can be saved in various formats, including HTML which is the chosen format for (free) books available on bookdown.org. Many of them are also published as physical books by publishers such as O’Reilly and CRC-Press.

Here is a very complex example of a book written with this method, published but freely available online as well:

Computational Genomics with R Altuna Akalin 2020-09-30

Manuscripts

Here are more examples offered online for manuscript

Resources

 

Credits