Read this if you think LaTex is too complicated, and you want to focus on writing content instead of formatting your the LaTex document.
Markdown is a standard text format that many text editors support. It's actually the format that README files use in repositories websites, like GitHub and GitLab. I use Markdown to write notes (revision notes for courses at Imperial, notes about books/ articles I read), and project work, including my Master's thesis, because it can generate LaTex documents. Below is a screenshot of what it looks like when I'm writing my notes in Typora.
When I'm thinking about LaTex or Overleaf syntax, I'm not thinking about the content. In I don't want to think about back-ticks to get quotation marks correctly, copying references into a
.bibfile, and other tedious tasks I don't want to force out from the depths of my slender Hippocampus.
word". Start with a backtick and end with a double or single quote. That is extremely weird.
.mdxfile, set the publish date, and
npm run build. I can also add some ReactJS components too.
If I'm writing a real report with references, equation and Figure numbers/ captions, then I use something called Pandoc (a CLI tool & library) to generate the nicely formatted LaTex output without touching LaTex. The entire LaTex ecosystem is complicated. I don't want to think about formatting or even see the formatting when I'm reading research papers and writing content. It breaks my train of thought. There is still a learning curve with using Pandoc. The benefit is that you can write in peace, and worry about formatting much less.
I write on the document on the left, and through a shell script, the PDF on the right is generated. In summary, Pandoc takes the markdown file, images, and reference style file (e.g. Harvard, IEEE reference style) and creates a PDF file. I don't even have the PDF open until I'm proof reading and making sure the formatting looks good. When I focussing, I will also disable the sidebar. So this is what I see when I'm writing this blog post right now.
I use Zotero, including the browser connector, which allows me to add PDFs, websites and articles to my Zotero library with one click. After using lots of open source projects in the past few years, I've decided to use the open source instead of Mendeley, because they often work well with other open source software, for example, editors and Pandoc.
First I tried to find the citation style that the conference enforces. After a while of 🤔, I realised there was no standard, when I compared a few papers from the conference that I am reading papers from. I noticed
ACM was popular from StackOverflow and reading articles.
I went with IEEE because it puts quotation marks around the title of the paper, which I prefer. I now use
transactions-on-intelligent-systems-and-technology available on Zotero Styles.
This was annoying to setup because there's a learning curve, but now it works blissfully. This guide is only for 🍏 users (Windows/ Linux users need to find an alternative to Typora). In summary, you need
Pandoc, Zotero, your Zotero library exported as a
.bib file, the BetterBibTex extension for Zotero, and style file
--bibliography). (File → Export → Better BibTex) your Zotero library somewhere, into the
ACM, and either install it to Zotero or download the
.cslfile. If you installed it to Zotero, you need to export the style from Zotero into a folder somewhere, for Pandoc to use it.
Citation Key, which is provided in Zotero. Every time you want to add a reference in your document, just use
[@citationKey], for example
Kolotouros et al. mentioned blah blah blah [@kolotourosConvolutionMeshRegression2019]. You can shorten the citation key in the Zotero settings, and I have done that now, so it looks like
1pandoc --filter pandoc-citeproc "report.md" --bibliography /Users/user/ZoteroLibrary.bib --csl /Users/user/ieee.csl -o "report.pdf"2open -a preview "report.pdf" # This will open the PDF with macOS Preview everytime you run the script
.YAMLsection to the top of your markdown file. So now when you click the reference it will jump to the references section. I also added the command I used to generate the PDF so I don't have to save it somewhere else.
1link-citations: true2# More useful YAML attributes:3numbersections: true4secnumdepth: 25number-sections: true6toc: true7lof: true8strip-comments: true9xnos-number-by-section: true10documentclass: report11---
This is helpful if you don't want to manually update figure numbers them in caption and all the references in your text, every time a new image gets added before it. StackOverflow is your friend. This question/ answer shows you. However, you'll soon find out that figures are not numbered per section, and are just ascending from 1, 2, 3 and onwards. It would be nicer to have Figure 1.1.3 instead of Figure 24. To fix this, you can use a Pandoc extension called Pandoc Fignos, by Thomas Duck on GitHub. There is a similar Pandoc extension, called Pandoc Eqnos, by Thomas Duck on GitHub.
Give Pandoc a custom theme (a
.tex file), and it will generate the report using that theme instead of the default LaTex layout. This allows for separation of concerns (a software engineering term, aka. SoC): you can create your own custom looking LaTex files to follow a standard template someone has given you, but you don't have to even look this complex file when trying to work on the content of the report. Pandoc's documentation on theming will come in handy as you explore this topic. It can get complicated. Your LaTex file has access to all the YAML attributes at the top of the markdown file. For example, my theme uses a special front page, so I use a
title: "This is the tile of my report" in my YAML, and the theme can these use this in the LaTex file, with
For Imperial College computing, students are required to use LaTex and are recommended to use a college-provided theme for many of their projects. I have modified the theme Imperial provided us with to work with Pandoc, and it is available on GitHub. There is a starter report you can use, so just set up the environment following the guide above, and don't worry about LaTex or Overleaf.
UPic is a plugin that allows you to upload images to the internet purely by dragging images into the Editor. This means you don't have to worry about file directories. For example, once you have an image you like, just drag it into Typora and it will be uploaded to your online account on Imgur. UPic requires configuration to know which account to upload, so follow the documentation for this. UPic allows you to upload to Imgur, AWS S3 buckets, and more.
Alfred: Alfred is a replacement for spotlight on macOS. Its a free software but the paid version has a lot more functionality. With the paid version, if I want to find a reference or a citation key in Zotero,
zot ResearchPaper will do that that for me.
I hope you've learnt something, and that your life is not consumed by LaTex, but by your research instead. I was worried about LaTex formatting a few months ago, but I'm happy to say I won't be worrying ever again.
Original photo by Neil Thomas on Unsplash.