Authorea review & questions

Overview

  • 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.

Questions

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:
    • layout.md: the master-document structure, plain list of references to other files (.md, .tex, also .html?)
    • title.md: contains the document title string
    • abstract.md: just the abstract text
    • authors.tex: appears when you try to modify the authors list through the web-interface. Can it be also authors.md? 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.

Diagrams

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: https://share.viewedit.com/fR73MTd6TBmTzEMi5yWHsZ

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: https://share.viewedit.com/3BKp1wiYutMJWUiuNqoWcr