How to connect a markdown editor with Authorea

Online scholarly collaborative writing is a great way to integrate different ideas together but it is also challenging for the following reasons:
  1. Most people are familiar with Office productivity and not with the new workflows possible
  2. Git is an important aspect of the workflow but git is not very easy to learn and not everyone learns Git
  3. Authorea and Overleaf are two great tools but neither are as widely adopted as most other tools such as Word
  4. Google docs is great for collaborative writing but Google Docs does not natively support several key things that are needed for academic writing.
  5. Bibtex is a very useful tool for plain text writing but Bibtex does not enjoy the same popularity as some other tools
Having said that, a great workflow might be as follows:

State of the art of the tools available

Office and Endnote bundle the most popular application bundle but they do not: - Work equally well in all platforms (making Word and Endnote play well in Mac is a nightmare, there is no Linux version) - Office is not the best for version control and can be very difficult to keep track of tens of documents - There are office integrations in cloud but how well they work is unknown
Overleaf and Bibtex (or Sharelatex and Bibtex) are excellent choices for plain text and bibtex with a web front end but again difficult to get people to use them collaboratively. Most people would rather use an office WYSIWYG version than use the robust nice plain text application of LaTeX. Besides, these systems are based on LaTeX. While LaTeX is great for writing and typesetting, it has very difficult rules for writing tables and figures and not very well supported by easily readable syntax.
Markdown and Pandoc combination are again excellent practices. Markdown in particular is very well documented and excellent for both machine and human readable plain text documents. However, original markdown was not really meant for academic writing and supporting tables and citations. Markdown has been extended for use of Scholarly writing the Scholdoc is a very good example, but Scholdoc seems to be out of date or not being developed actively for some time. Pandoc on the other had is really a good option and offers plenty of grunt for conversion of documents to many different formats.
Several markdown and pandoc based document converters exist and these are really good. Madoko for example is a very nice WYSIWYG editor with plenty of features. Authorea is another that allows markdown, latex and other tools to interact.
These many tools offer a range of features where some features are good with some apps, and other features are great with others, but there is not yet one application that can offer all the best features in one app. These are namely:
  1. An ability to write in plain text or in rich text format (Overleaf and Authorea excel)
  2. Integrate with plain text editors (Sharelatex, Authorea and Overleaf excel in this)
  3. Allow for headers, paragraph, tables, figures, citation, version control and pushing to repositories (a few, notably authorea and overleaf)
Authorea allows for markdown, html (text writing), and latex writing but not sure how well latex writing is supported. The latex writing interface and the markdown writing interface are not integrated with the rich text interface. Their html writing interface is a rich text writing environment on the web browser and this is helpful. Overleaf is LaTeX based and allows for some RTF writing, although their RTF interface does not support tables, citations, and figures intereactively. This is the strength of Authorea. Authorea also can read files in a wide range of formats, making it easy to interface with other formats, it can also export files to a number of different formats.
One way to work through this morass of information and making it easy for collaboration might be to keep developing the document in Markdown and interfacing using Github as a bridge with Authorea. That way it will be helpful for one to write a paper in Markdown and use Pandoc to convert the document to HTML (which Pandoc supports very well). Then push the HTML document to Authorea for further processing and seeking inputs from people who may not be familiar with markdown or other writing formats than rich text. Add citations and tables, etc and then bring them back to markdown for processing.
If two or more collaborators are familiar with Markdown (even if they are not, Markdown is not difficult to write), then collaborate using Github, otherwise, those who are not familiar with Markdown, they can collaborate on the Authorea interface directly.

The purpose

Here is a workflow where one starts with Authorea to create a document and then uses Markdown locally to control the document using Git. The workflow goes somewhat like this:
  1. Create a document first in Authorea
  2. Create a git bridge and integrate with github
  3. Create folders of bibliography (Authorea creates bibliography folders in a folder titled bibliography and in it places a file titled biblio.bib)
  4. Write the document using local Markdown app
  5. Update the Authorea document from Markdown app locally
  6. Edit Authorea and pull in the changes through git

Creating a document first in Authorea

This is the easy part. Log on to Authorea and create a document. It is possible to create a blank document (at least provide a title) -- that is the minimalist approach. Alternatively, it is possible to insert sections in the form of html (text) chunks. The caveat here is, in the author section, one needs to uncheck automatic naming of the sections, so that this can be reset after creation of sections. For this, one needs to open up the layout.md file from the drop down data block and rename the files one after the other (a bulk editing is not implemented in Authorea). The html files are renamed. Check the layout.md file and only those files listed there will show up in the Authorea interface. If you want, you can also create a bibliography folder with biblio.bib here.

How to create a git bridge and integrate with your git client

The easiest way in Authorea is to "set up the github connection automatically". Then visit github your own repository (you have to get a username) and clone this repository locally. The code to do that in your terminal is as follows:
git clone URL to be cloned
Write Markdown locally and convert the document to HTML
Two steps here:

Step I: Rules of writing Markdown

Markdown is an easy web enabled writing system. John Gruber, a blogger and web commenter invented this and its documentation can be found in his website. This system has now been expanded to include tables and citations. In order to interface with Authorea HTML however, you need to use the Pandoc flavoured markdown where you write tables with pipe symbols, and add citations using the same way as you would write citations in LaTeX but with the following code for citations:
Note the two black slashes. The class statement is specific to Authorea. There are other ways to write for citations (see Pandoc documentation). So if you want to add a citation:
  1. Add or make sure that the citation is first entered in the bib file
  2. Then add the citation ID with the above code
Here is a reference to the Johnston article  on JATS \citet{johnston2016}.

Step II: Convert the markdown to HTML and HTML to markdown

Code for conversion from markdown to html
pandoc main.md -f markdown -t html --parse-raw -o main.html
Code for conversion from html to markdown
pandoc main.html -f html -t markdown --parse-raw -o main.md
A few points, note the output flag. You can change the output file name to something else.

Interact with Authorea

This is done with git. So the markdown document is pushed to its own github repository and you can work from there. Just make sure to stage only those files you change.
Comments
This is not yet perfect, and may even be klunky, but just about works. Once you make changes in Authorea, you need to go back and git pull the document. Then convert the document to markdown and work on the document and then push again, this time only the html file (do not push everything, you can keep them in the staging area: this is a git issue, read on git). If you mess these things up, then a whole world of merge nightmares pop up. Everything else should work just as planned. Just keep in mind the citation codes, for some reason the showing of the codes in html did not work. But at least using this workflow (that is writing in markdown, converting it to html, pushing it to Authorea, changing the document on Authorea, pulling changes, converting back to markdown, making changes, converting forwarding to html and pushing through git), you can get by using markdown and writing on the web. You need to use git quite efficiently for this workflow to be successful. There are easier workflows for other editors such as Overleaf, but at least this offers a great flexibility of writing online on the web and on your machine locally using markdown. Also, interfacing with github adds to the beauty of working with github directly. You can add and update tables, figures, citations, and format citations in any way you like with basic pandoc. The scheme does not work very well in Firefox developer edition, but on most other browsers, the system works well.