Markdown

Author

Jon Reades

Published

September 7, 2023

Markdown is a ‘markup language’ for documents that is compatible with a lot of different tools (including GitHub and Jupyter) that we use day-in and day-out for doing our research and teaching. Many of us have now largely stopped using Word (and even LaTeX) except for the final polishing of a document. Why? Because Markdown is faster, simpler, and just gets out of the way when we’re writing. So rather than fiddling about with Word’s styles (or, worse, discovering that you should have been using styles all along) or with LaTeX’s painful table layout, you can just get on with writing in Markdown and then export to Word or LaTeX for the final steps. Best of both worlds!

In fact, Markdown is so handy that it’s become the default for writing content for the web. This web site was actually written in Markdown and then ‘rendered’ (i.e. turned into a functional web page) using Quarto. We’ve included Quarto on the SDS2022 Docker image that we’ve recommended you use.

Markdown Editors

Over time you will undoubtedly learn how to write markdwon without need to think much (if at all) about how to type the formatting ‘codes’, but a simple markdown editor can make your life much, much easier. Even when you’re highly experienced!

There’s a good overview of ‘free’1 editors for the Mac which highlights a few in particular:

  1. MacDown – I’ve not used this, but it seems determinedly FOSS so is probably a good choice.
  2. Haroopad – this looks like a more powerful, but less immediatley user-friendly editor.
  3. Atom – I’ve used Atom for editing Python code but believe it’s largely plugin-based so it clearly supports markdown too.

Typora was free while in beta, but I thought it was worth the modest amount of money asked for something that was super-fast and gave me a tool with which to write up my research, not just my code and teaching content. iA Writer is another good (paid for) option because it runs on iPad and iPhone as well! Together with the Working Copy Git client for iOS I’ve used iA Writer to draft articles, make notes directly in my codebase, and correct errors found at the last minute in my teaching materials. Like Typora, iA Writer is probably intended more for writing text, not writing complex Reveal.js presentations or non-standard markdown.

I don’t have access to a Windows machine to test this out, but there are plenty of opinions to be found by Googling ‘best Windows Markdown editors’ or ‘best free Windows Markdown editors’. There’s one for writers and a more generic set of recommendations. Have a look around and see what you like!

If you use Linux already do you really need a recommendation? How about vim or vi?

Using Markdown

For Markdown to be useful as more than just a lightweight way to write notes, we want to be able to render it into new output formats/contexts. Here are three…

Markdown & GitHub

Markdown is the ‘default’ language of GitHub, which means it’s worth your while to familiarise yourself with how it works. However, there are different ‘flavours’ of markdown, which also means that just because something works on GitHub it will work everywhere else in the same way. This is particularly common when dealing with optional parameters that try to give the ‘renderer’ (the thing that converts markdown to HTML, or LaTeX, or any other format) hints about how the content should look.

Markdown & Notebooks

Markdown is also the language of plain-text cells in Jupyter notebooks, which makes it doubly worth your while to familiarise yourself with how it works.

Quarto

Quarto builds on RMarkdown to make the power of Markdown+Code available to other languages than R. In our Foundations of Spatial Data Science module we use Quarto to do submissions but that’s largely because it demonstrates how we can Quarto to write whole articles or dissertation!

In many cases, it is as straightforward as installing Quarto and then running quarto render ..., but there are some tricks. In particular, to ‘render’ Markdown files to PDF, you will need to have some flabour to TeX installed. The default suggested by Quarto is TinyTex, and this can be installed using:

quarto install tool tinytex

But on some platforms there are additional issues:

You will probably be able to successfully install tinytex, but then be told that no TeX installation could be found when trying to render. The issue relates to the $PATH where Quarto searches for a valid TeX installation and when completing the installation you may have seen a warning to the effect of “To complete the installation, please run the following…”

So that’s basically what we need to do. The first thing you need to do is find the TinyTeX binaries, in the cases that I’ve been able to fix these were found under something like $HOME/Library/TinyTex/bin/, but you may need to look further under $HOME/Library/ to find the TinyTex directory.

Once you know where TinyTeX is (adjust the cd command below as necessary), you can then follow the suggestion given:

cd $HOME/Library/TinyTeX/bin/
./universal-darwin/tlmgr option sys_bin $HOME/Library/TinyTeX/bin
./universal-darwin/tlmgr path add

That should do it, but in case you are still getting errors, then the following might be necessary (again, adjust the path if necessary):

echo "export PATH=\"/Users/$(whoami)/Library/TinyTeX/bin:\$PATH\"" >> $HOME/.zshrc

The command above uses whoami to set the username and assumes that’s how things should be set up, but don’t blindly copy+paste and assume this will work! You could, for instance, check this location exists first using: ls /Users/$(whoami)/Library/TinyTeX/bin/ That will show if the path exists! The above command then updates the $PATH variable used by your Terminal to look for binaries, enabling Quarto to find TinyTeX once you close and then re-open a new Shell.

Most commands seem to require replacing quarto with quarto.exe to run correctly. So quarto render Template.qmd becaomes quarto.exe render Template.qmd.

However, if you are still getting errors to the effect that Quarto cannot be found then you may need to make additional edites to your .bashrc file (this is the configuration file for bash):

  • Check where Quarto is installed, it is most likely under /mnt/c/Users/<Your Username>/AppData/Local/Programs/Quarto/bin (replace <Your Username> as appropriate.
  • Edit the .bashrc file in your $HOME directory. On Windows I would Google search for the best way to do this: “edit .bashrc file Windows”.
  • Add the following line at the end of the file: export PATH=/mnt/c/Users/<Your Username>/AppData/Local/Programs/Quarto/bin:$PATH
  • Save the file and run source .bashrc in the Terminal.
  • You should now be able to run the following command successfully: quarto.exe --help

Footnotes

  1. Not all of these are still free.↩︎