This repository should be everything you need to get started with writing your thesis in asciidoc. The text in the template is based on the latex-templated provided the Artificial Intelligence Group at IDI. It should give some hints on how to structure your thesis, as well as show you how to use the different features of asciidoc. If you would like to see a completed thesis using asciidoc you can take a look at our thesis.
First you will need ruby and it’s package manager gem. For mac we recommend installing Ruby Version Manager (RVM). This guide will help to install ruby and RVM. We used Ruby version 3.0.0, but there is no reason that a later version would not work.
After ruby is installed, you can use the package manager gem to install the asciidoc gem.
gem install asciidoctor
gem install asciidoctor-bibtex
gem install asciimathWe’ve set up three different methods for compilation. They are all based on rendering in Chrome, and we recommend using that browser.
When compiling the thesis locally, you get the benefit of hotreloading.
To start locally run:
source hot_reload.sh
Hot reloading currently only works on mac, however we invite any contributions to port the script for other OSs.
If you want to run locally without hotreloading, you can run:
asciidoctor -r asciidoctor-bibtex -a stem -a docinfodir="./configuration/local" index.adoc
Asciidoc has the benefit that it compiles to HTML, and as such it can be hosted as a website with very little effort.
This makes distribution to supervisors very simple, and allows us to use known methods of version tracking for providing our text.
We suggest hosting the website on netlify, but any hosting service would be appropriate.
If you wish to run the web version of the thesis locally you can run:
asciidoctor -r asciidoctor-bibtex -a stem -a docinfodir="./configuration/web" index.adoc
At some point you will need to create a print ready document for your thesis.
There are many ways of creating PDFs from asciidoc, however we decided on using the browser print engine together with the library Paged.js.
To run the print version of the text you can run:
asciidoctor -r asciidoctor-bibtex -a stem -a docinfodir="./configuration/print" index.adoc
After compiling the document you can open the file in the browser and tweak the css file to ensure that page breaks happen just where you want them. We suggest doing this when the text of your thesis is 100% complete. Finally you print to pdf with your browser.
If you want to deploy this to netlify this is the build command you use:
gem install asciidoctor asciidoctor-bibtex && asciidoctor -r asciidoctor-bibtex -a stem -a docinfodir="docinfo/prod" index.adoc
In general asciidoc is supposed to be as light weight as possible. If you’re familiar with markdown you should be familiar with most of the syntax, but in general you just write text, with a few symbols to provide emphasis. The main difference from markdown in syntax is that headings are labeled with a equals sign, rather than a hash sign. There are plenty of cheatsheets out there, this and this are two we like, however google will serve you well in most cases.
As opposed to markdown, asciidoc supports more advanced features that you might recognize from latex. In our case we needed citation support, section references and mathematical formulas. These come with more syntax, and you should reference the template to see how to use them.
One particular thing you might note is that sentences should always start on a new line in asciidoc. This is very useful for a few reasons. Firstly, it makes diffs in git very clear, as git works on a line by line basis. And secondly it makes it easy to understand the flow of your paragraphs. Identifying that you start sentences the same way regularly becomes trivial.
Citations in this template are controlled by the library.bib file. While you could generate this file by any means, we recommend using Zotero. Zotero is a bibliography manager which allows for automatic syncing between users, and is available for download from here. We recommend creating a group and inviting your writing partner (if you have one) and potentially your supervisor. You should also download the Zotero browser extension from here. You will also need the Zotero plugin, better-bibtext from here.
After you got everything set up you add new citations with the browser plugin, maintain those citations in the Zotero app, and export to a bibtex file from Zotero to the repository.
To export the .bib file you right click on the library in Zotero and click Export Library.
From here you select Better BibTeX from the list and check the box for Export Notes.
If you also click the box for Keep Updated the file should be autogenerated any time you add a new citation, or update an existing one.
Then you will simply need to add it to git every time you notice a change.
You can change the name of the bib file by editing index.adoc.
Please do note that Zotero is note bug free. However, despite some small annoyances the tool proved invaluable to our work with our thesis and it still gets our warmest recommendations.
We used Grammarly extensively while writing our thesis. Grammarly is a web-based grammer and spell checker. The free version is fine, but we believe it is too limited for writing and extensive accademic text. We recommend using the paid version, which is available for download from here.
If you decide to use Grammarly, you absolutely must ensure that your settings are set up for your thesis. Grammarly allows you to decide style of writing, formality level, tone and a few other settings. Tuning this greatly improves the benefit Grammarly offers in writing a thesis.
If you are using VSCode there is an unofficial extension for Grammarly, which you can download from here. This plugin is certainly not bug free, and can at times be quite frustrating. However, being able to get live feedback on your writing is a huge bonus. We recommend fighting with it until you get it working. When you are getting close to done with your thesis we also copied out sections of the thesis into the webview of Grammarly, to catch any errors that confused the plugin. We copied from our live website version, to avoid the syntax additions from asciidoc.
One of the benefits of leaving Overleaf and LaTeX, is that it is very easy to use any editor you want. If you happen to agree with us that VS Code is a great alternative, there is also a asciidoc extension. You can find the extension here: here. The developers are very accepting of contributions and we have written two additions which allow for autocompletion from section ids and bibtex entries.
When searching for tools to replace LaTeX, we came across this video which set us upon the path of asciidoc.