# Overview

• Markdown editing with feature-rich web-editor (Pandoc + MathJax)
• 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

# 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