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.
- A Plain Text Workflow for Academic Writing with Atom
- Sustainable Authorship in Plain Text using Pandoc and Markdown
- How to use Pandoc to produce a research paper
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
- Book in HTML, freely available:compgenomr.github.io/book
- Rmarkdown source code for the whole book: github.com/compgenomr/book
- The printed book is 462 pages, published by Chapman and Hall/CRC has a list price of $130.
Here are more examples offered online for manuscript
- Blog: Scientific Writing with Markdown Jaan Tollander de Balsch
Last updated on 2020-12-21 – 10 min read
- Video, in-depth review: Setting Up a Scholarly Writing Environment With Markdown, VSCodium and pandoc (1h49min) – by Shaping Openness
- Video: How to Create Scientific Essays with Markdown and Pandoc (5.02 min) – by Jaan Tollander de Balsch
- Video: Using Pandoc (10:05 min) – Nicholas Cifuentes-Goodbody (Not necessary if you use RStudio/Rmarkdown method)