Authorea review & questions


  • Markdown editing with feature-rich web-editor (Pandoc + MathJax)
  • Overall academic writing focus
  • Github integration
  • Commenting on the document (discussion/supervision)
  • Advanced and easy citing (with BibTeX bibliography)
  • Collaborative editing with some kind review/approve interface and conflicts resolution
  • Storing datasets, pictures and bibliography together with the article
  • Export to LaTeX/Word/PDF (HTML?)
  • A big library of templates for scientific journals
  • Convenient pricing: 1 private project for free, different individual/team plans for more
  • Actively developed (open roadmap)

My use-case

I generally see Authorea as a medium for collaborative writing. I know that there's much more about publishing, but I'm still a bit far away to be concerned about it.

Personally, I prefer to use a local setup with my customized editor, Pandoc for generating output, Git with meaningful commit messages, etc. And I want to use Authorea as an interface to be used by other coauthors (my supervisors or colleagues) that don't want or don't need to use git/command line directly: for reviewing, commenting, minor fixes and additions that can be easily done through the web-editor "in-place".

So it's important for me to understand how I can write locally, but in a way that won't break the appearance of the article on the web-side exposed to other coauthors.


Folders structure and special files

What I haven't found in the docs is the way Authorea manages the git repo and processes the special files:

  • What is the general structure of the underlying git repo, what parts are mandatory and what optional?
  • Which special files are there in general and which formats do they use? Here are the ones I found out so far:
    • the master-document structure, plain list of references to other files (.md, .tex, also .html?)
    • contains the document title string
    • just the abstract text
    • authors.tex: appears when you try to modify the authors list through the web-interface. Can it be also Anything else? (see my Pandoc YAML header feature request)
    • header.tex: TeX preamble (related doc). Not clear how it is incorporated in the rest of the template used by Pandoc internally.
    • bibliography/biblio.bib: BibTeX bibliography. Does the name matter? Why the folder? Can I have several files there?
    • figures/: folder for pictures. I'm not sure about the structure and format.

Pandoc and the build process

  • Is there a way to pass any options to Pandoc?
  • Which Pandoc extensions are turned on by default?
  • Is there a way to use XeTeX engine for being able to use Unicode everywhere?
  • Is there any way to setup a custom build script for generating the document? I expect no in general, because it would be a security vulnerability, but probably some kind of TavisCI-like config is used internally and could be exposed to the user.

Update: it appears that there are various solutions to what I described above (wrappers for Pandoc with YAML config to handle any Pandoc options and pre/post-processing):

And probably more.


My field is algebra, so I need to draw a lot of commutative diagrams and string diagrams. I'm using TikZ package, but here the diagrams code is not rendered at all.

Probably a generally better way to work with it is to have diagrams LaTeX/TikZ code separate and generate SVGs for each of them, then just insert the pictures in the main document. But then I have to setup some other CI service to generate those pictures.

Found bugs

General issues

  • Inline code rendering is funky: the box is too high, getting off the line, also \[...\]
  • Usual markdown syntax ![](...) for inserting local pictures doesn't work (see below)
  • Math formulas are not rendered properly $e^{i \pi} = -1$: sometimes they are, sometimes not. I'm not sure what's the pattern. Sometime changing $...$ to \(...\) and $$...$$ to \[...\] helps, sometimes not.
  • Sometimes when editing a paragraph, mouse-click brings me to the top of the page, which is very annoying:

See an overview of LaTeX math-mode problems here.

Related to the new editor

  • Pushing to Github manually doesn't affect the document. But I can see the commit in the History tab on Authorea. If I open The post in incognito-mode, I see the latest version, but the logged-in editor shows me the old one. Switching to the old editor helps. I guess the new editor is not ready for wide use (at least in Chrome) yet.
  • No way to delete an empty paragraph (except going to the Data section and deleting the file). Also empty paragraphs become invisible and may accumulate in the repo.
  • Sometime clicking on a paragraph brings some completely unrelated text to the edit area:

Feature requests and ideas

  1. Use Pandoc YAML metadata block extension for storing information about

    • article title,
    • authors and their affiliations
    • keywords/tags (which is also useful for blog-posts)
    • abstract
    • date, etc.

    This would replace with say metadata.yaml:

    • generated by Authorea
    • easy to extend/change manually
    • keeps all information about the article within the repo (currently authors information is missing)
    • this could also allow to set Pandoc variables to be used in templates
  2. In addition to the YAML metadata extension it would be awesome to support panzer styles: a simple way to pass options to Pandoc and adjust any kind of document-specific styling.

  3. Editing document sections/chapters separately within common web-interface. I see that one can access to the Data of a document and paragraphs/sections are stored as separate Text