TUGboat, Volume 41 (2020), No. 2

197

learnlatex.org: Taking LATEX training
fully interactive
David Carlisle, Paulo Roberto Massa Cereda,
Joseph Wright1Introduction

There are a plethora of resources available to new
LATEX users. However, it is much more difficult to
discover which of these provides the best introduction
to LATEX. These online resources vary in quality andcorrectness: over time, and with limited editing,even good advice can become out-of-date. Many
good resources are over-detailed for a new user whoneeds only straightforward help to get over the initialbarrier to using the system.
For many programming languages there are now
web sites providing the opportunity to try coding
online using a cloud compiler. These cloud compilers
can be harnessed by a range of teaching websites tooffer a simple introduction to the language using asuitable IDE (integrated development environment);a good example is LearnPython.org. Such sites
tend to be limited in scope as they are not aiming
to teach every possible idea in the language but only
a “Beginners” menu.
Over the past six months, work has been ongoingin filling that gap for LATEX: learnlatex.org. The
aim of this new site is to provide a carefully-curated
set of resources for beginner LATEX authors, withintegrated use of an online LATEX environment anddemonstrations accessed directly from these lessons.
The scope of these learning resources is focussed, andwith the aim of offering the material in bite-sized
chunks.
2

Existing resources

There are already many online resources for learning LATEX, as a simple web search will reveal. The
top hit at present is Overleaf’s “Learn LATEX in30 Minutes” (https://www.overleaf.com/learn/latex/Learn_LaTeX_in_30_minutes), which covers
many of the core ideas with a series of examples.
The second is https://www.latex-tutorial.com,
which takes the step of dividing up the lessons into aseries of pages. There are then more “traditional” resources, including the long-standing LATEX Wikibook(https://en.wikibooks.org/wiki/LaTeX), and ofcourse many excellent printed LATEX guides.
The Overleaf page is notable as Overleaf provides
a full LATEX system online, and is used by manypeople as their LATEX editor/system. On their teaching page, the examples are given as code blocks but
to run then, a separate tab needs to be opened. That

has the positive of looking exactly the same as anyother document edited on Overleaf, but means leaving the teaching page. The other leading hits forlearning LATEX require that the learner copies ortypes out the examples by hand.
In contrast, users learning other programming
languages can today often start on websites that letthem try out the system in the page. That meansno copy-pasting, no need to move to other tabs,
and no need to download and install software. Asmentioned above, LearnPython.org is an excellent
example, forming part of a family of around halfa dozen sites using the same overall framework toteach a set of modern languages.
The learnlatex.org project was started withthe aim of combining existing best-practice teachingon LATEX with a strong focus on interactive, online,training. That required tackling three things: thecontent, the website structure, and the online element.
3

Writing content

The starting point for writing the content was longstanding material developed by Nicola Talbot andused by the UK TEX User Group (UK-TUG) for faceto-face lessons (https://github.com/uktug/latexbeginners-course). After assembling a small groupof volunteers, we began by looking at this curriculum,
the content of other sites and discussions we have
all had with new(er) users. That led to a first set of
section titles, which we adjusted as new ideas arose.
We then started drafting the content, taking
existing notes plus new material to deliver around
15 lessons.1 As we worked through these, we found
we had more to say than was reasonable to cover ina focussed set of lessons. We also felt there was goodcontent that did not belong in the basic lessons, but
did belong somewhere. That led to a split of eachlesson into two parts: the basics and “going further”.
(We’ll look at the file structures below, and how theybuild the site.)
As well as the content and demonstrations, we’veworked hard to make sure that the lessons are upto-date and accurate. That’s led to discussions with
the LATEX team about for example \label, which isreflected in the lesson content and means that weare confident the site covers best practice.
4Website structure

Based on experience with texfaq.org, we knew thatGitHub Pages, which lets you write webpages inMarkdown, was a good place to look to host the site.
1 We’ve grown to 16 lessons, as there was a strong argument to add one on errors.

learnlatex.org: Taking LATEX training fully interactive

198

TUGboat, Volume 41 (2020), No. 2

This means that multiple authors can easily workwith the sources without needing to set up a complex
build system: the pages can be edited on the GitHubsite, so a local Git installation is not even required.
We started with a simple structure, with anindex and 15 lesson-XX files (all in Markdown, ofcourse). GitHub Pages runs a system called Jekyll,
which turns those files into the full site. That’s doneusing various bits of template plus some scripting,which can all be user controlled. As the site hasgrown, we split the extra content into more-XX files,
which can then be linked automatically to their “parent”.
Not long after we started work, the question oftranslations came up. We’d started with the ideaof just working in English, but we didn’t want tobox ourselves in. So we moved all of the content
into a directory called /en, and started exploring
how to add a language selector. To help with that,
we made some stub files that were marked as being
in a few languages, then got at least the page titles
translated by real people. It turns out to be reasonably easy to add a selector, and there’s already beeninterest in translation, so we have the site in English,
Vietnamese and Portuguese already, with Spanish,
German and Japanese in the pipeline.
Linked to translations, we also realised thatwhile most of the lessons stay the same for every
language, we needed a place where language-specifics
could be covered. That came up when we wereasked about Japanese; they need vertical typesetting,which of course is very different from what we needfor English. So a place for non-translated pages has
been added: the content and number of pages there
is down to the translators.
5

Online LATEX compilers

As outlined above, a key aim in developing the site
has been to allow examples to be run as close as
possible to “in the page”: that has led us to explore
a range of options in this area. We wanted to have afull LATEX system available, which mean that systems
such as MathJax (mathjax.org) or even MiniLATEX(minilatex.app) were not suitable.

that the examples should cover a range of languages
and so a range of TEX engines should be available,
notably pLATEX, LuaLATEX and XELATEX in addition
to pdfLATEX.
During initial development of the site, we mostly
used the servers latexonline.cc and latex-on-http(https://latex.ytotech.com/). However, in theend we developed a server latexcgi.xyz specificallytailored to the requirements of the site.
The most noticeable distinguishing feature of
the LATEX CGI server is that it does not directlyreturn the generated PDF but instead returns acall to a locally hosted copy of the PDF.js (https://mozilla.github.io/pdf.js) JavaScript library.
This ensures consistent behaviour, notably on mobile
browsers which typically do not include a built-in
PDF renderer. The server does support options toreturn the PDF directly, or to return the log file, evenof successful runs.
LATEX CGI supports a range of LATEX formats:lualatex, pdflatex, xelatex, uplatex, platex andtheir -dev variants. It also supports biber, bibtex,pbibtex and bibtex8 and makeindex.
The server has installed a full copy of TEX Live2020 and runs in the default “restricted shell escape”
mode. This means that packages such as imakeidx
that make use of the allowed shell commands areavailable.
Currently latexcgi.xyz is hosted as a virtualmachine on Amazon’s EC2 service, which is available
in the Free Tier for one year. Long term hosting has
yet to be finalized.
Using a dedicated server gives some flexibility
in the technologies used. One possibility would beto use Docker images such as the TEX Live images
provided by Island of TEX (https://gitlab.com/
islandoftex/images). This would likely be necessary if we decide to offer more programming features,in particular allow TEX to be run with shell escapeenabled, although currently the intention is to matchthe default (restricted shell escape) that matches atypical user’s system.

5.2
5.1

Processing examples “in the page”

It is possible to run TEX in the JavaScript engine in
the browser and initially we did some experimentswith texlive.js but such systems are hard to keep
up to date and currently provide only pdfLATEX, notother engines such as LuaLATEX. So the decision wasmade to use a server which ran LATEX, returning thegenerated PDF to the web browser. An importantconsideration when choosing the technology here wasOnline TEX processing systems

All the systems mentioned in the previous section
have the feature that they require no login or preregistration, which is convenient but means that anyedits to the documents are lost when the user moves
off the page. The site therefore offers a second alternative to access a full online TEX system provider,currently Overleaf.
If the Open in Overleaf button is used, a new
project is opened in Overleaf in a new tab in theDavid Carlisle, Paulo Roberto Massa Cereda, Joseph WrightTUGboat, Volume 41 (2020), No. 2

199browser. The user can edit the example in Overleaf,
and save the project if desired, to return to it later.
The Overleaf API was extended for this site, toallow multiple-file projects to be uploaded in thisway.
Other TEX editing systems could be used buta requirement is a public API that starts a project
via an HTTP request rather than using the web pagemenu interface.
6

What’s next

The web design we are using is very basic: just whatcomes out-of-the-box with GitHub Pages. To help
users navigate, we need proper development of a fullsite. That’s beyond the expertise of the site team,
but we have been able to raise funds to employ aprofessional web developer. He’s looking at design
both in terms of appearance and structure: things
like mobile accessibility, metadata, etc., are all reallyimportant.
There’s also still more to do on the content, inparticular working out if we need more formalised
exercises or lesson summaries. That likely needs user
feedback, for which we need your help. The site
will work best if it’s promoted to potential users,
and readers of TUGboat are we hope well-placed torecommend it. Of course, to do that, we’d encourage
you to read the site, give feedback and perhaps evensuggest some improvements!
 David Carlisle
Oxford, United Kingdom
d dot p dot carlisle (at)gmail.com
 Paulo Roberto Massa CeredaSão Paulo, Brazil
paulocereda (at) gmail.com
 Joseph WrightNorthampton, United Kingdom
joseph dot wright (at)morningstar2.co.uk

learnlatex.org: Taking LATEX training fully interactive