Zotero with AsciiDoctor and Visual Studio Code

by: Artur Dziedziczak

April 24, 2020

Some time ago I started to work on my thesis and the first thing that came to my mind was the need for proper tool for article gathering

The requirements were simple. The tool that would fit my needs:

  • should allow to gather scientific papers and catalog them
  • should allow to write text in Markdown-ish syntax
  • should allow git to make versioning on documents (more or less it should be a text format)
  • should allow to make a bibliography and add citations

and one not that important but it really makes a difference

  • should allow to move around written text with VIM shortcuts

Sadly after some research I found that there is no one Swiss Army Knife tool

I experimented with:

  • Google docs
  • VIM with plugins
  • Visual Studio Code with plugins
  • Evernote

But none of them really solved all the issues and some of them were a pain in the ass to work with. Like for example VIM plugins…​

And at the point when I almost started to write thesis in Latex…​

I remind myself that there is a tool Zotero

Step 1 of 4 - Setup Zotero

Zotero [1] is a general tool that allow you to quickly add articles, citations to a common database of your project. With connectors to Firefox and Chrome after you visit websites you can easily add content you want to your Zotero project and then cite or make bibliography with the usage of Microsoft Office Word or LibreOffice

How it works?

To set it up you need to follow these steps:

  1. Sign up on website and download Zotero: https://www.zotero.org/
  2. Open Zotero tool and login. It should look more or less like this:
  3. Install connector for Chrome or Firefox: https://www.zotero.org/download/connectors
Figure 1. My Zotero after sign up and installation of the tool with a connector to Firefox

Now everything should be setup and you should be able to add your articles to Zotero project. To do that in Firefox you have to:

1) Visit website/article you are interested in

2) Click on the connector and choose where you would like to put an article

zotero highlight
Figure 2. Zotero connector in Firefox

And that’s all. Now article was added to your database and should be visible in Zotero application

zotero added
Figure 3. Zotero added article

Step 2 of 4 - Setup Bibtex for Zotero

Visit website https://retorque.re/zotero-better-bibtex/installation/ and follow their instructions

When it’s properly installed you should see that in Zotero you have new options

Figure 4. Zotero after Bibtex installation

Step 3 of 4 - Setup AsciiDoctor

You are probably familiar with Markdown. It allows you to write simple, well-formated documents like documentation for the Github project

AsciiDoctor is similar, but has more features

Asciidoctor is a fast, open source text processor and publishing toolchain for converting AsciiDoc content to HTML5, DocBook, PDF, and other formats. Asciidoctor is written in Ruby and runs on all major operating systems. [2]

To install it you need to follow instructions on website https://asciidoctor.org/docs/install-toolchain/

After installation two more packages are needed:

  • asciidoctor-bibtex [4] - allows to use citations and create a bibliography
  • asciidoctor-pdf [3] - allows to convert asciidoc to pdf

If you completed instalation of AsciiDoctor you can install them by typing following command in console

gem install asciidoctor-bibtex asciidoctor-pdf

Step 4 of 4 - start writing with Visual Studio Code

Figure 5. Make file with .adoc extension that will be your main project
Figure 6. Install AsciiDoc plugin for syntax highlighting
step3 1
step3 2
Figure 7. Download .bibtex file from zotero and save it in project directory
Figure 8. Saved .bibtex file in project

Add lines with config for ascii-doctor-bibtex at the top of your ascii-doc document

Listing 1. Top of my-doc.adoc
:bibtex-file: my-library.bibtex
:bibtex-order: alphabetical
:bibtex-style: ieee

And now you are ready to make citations. Let’s make some

Listing 2. Full content of my-doc.adoc
:bibtex-file: my-library.bibtex
:bibtex-order: alphabetical
:bibtex-style: ieee

How to use citation. citenp:[WhenHowUse]

# Here is my bibliography:

After that you need to run asciidoctor so the .pdf file will be created. To do that open terminal and type: asciidoctor -r asciidoctor-bibtex -r asciidoctor-pdf -b pdf my-doc.adoc

The output file should look like this:


At this point you might wonder how Zotero connected citation with AsciiDoctor. It’s all bases on key of citation that is inside downloaded my-library-bibtex file

When you open it you should see content which format looks like this:

Listing 3. Contents of my-library.bibtex
  title = {When and How to Use Masks},
  file = {Zotero/storage/B9LUPTU9/when-and-how-to-use-masks.html},
  howpublished = {https://www.who.int/emergencies/diseases/novel-coronavirus-2019/advice-for-public/when-and-how-to-use-masks},
  language = {en}

As you can see the key for this particular citation is WhenHowUse. It was automatically generated and can be changed inside Zotero

Figure 9. Zotero article with generated key

Now everything should be setup

One more thing. Generally you will have to use this asciidoctor command after every save. It’s good to make a Visual Studio Code task for that

  1. Click Terminal
  2. Configure tasks
  3. Choose Create tasks.json file from template
  4. Choose other task
  5. Paste in the task.json
Listing 4. Contents of .vscode/tasks.json
    "version": "2.0.0",
    "tasks": [
            "label": "build",
            "type": "shell",
            "command": "asciidoctor -r asciidoctor-bibtex -r asciidoctor-pdf -b pdf my-doc.adoc",
            "problemMatcher": [],
            "group": {
                "kind": "build",
                "isDefault": true

This will create a build task that will be invoked everytime you press Ctrl + Shift + B

Final notes


Whenever you want to change key of article of any other field you have to use Zotero tool and download .bibtex file again. Don’t modify my-library.bibtex


[1] “Zotero | Your Personal Research Assistant.” https://www.zotero.org/

[2] “Asciidoctor | A Fast, Open Source Text Processor and Publishing Toolchain for Converting AsciiDoc Content to HTML5, DocBook, PDF, and Other Formats.” https://asciidoctor.org/

[3] “Asciidoctor/Asciidoctor-Pdf: Asciidoctor PDF: A Native PDF Converter for AsciiDoc Based on Asciidoctor and Prawn, Written Entirely in Ruby.” https://github.com/asciidoctor/asciidoctor-pdf

[4] “Asciidoctor/Asciidoctor-Bibtex.” https://github.com/asciidoctor/asciidoctor-bibtex, Apr. 2020