
Madoko – Write full-blown academic articles in Markdown - talles
https://www.madoko.net
======
AaronO
You also might want to take a look at GitBook
([https://www.gitbook.com/](https://www.gitbook.com/)).

It supports both Markdown and AsciiDoc and is used by authors to write books,
documentation, research-papers (GitBook has great TeX support, in all outputs:
web, pdf, epub, mobi). (Here's a math heavy book for example:
[http://jandeleeuw.gitbooks.io/bras1/content/blockrelaxation/...](http://jandeleeuw.gitbooks.io/bras1/content/blockrelaxation/bls.html))

The format and toolchain itself is open-source
([https://github.com/GitbookIO/gitbook](https://github.com/GitbookIO/gitbook))

There's a ecosystem built on top of that such as a Desktop Editor
([https://www.gitbook.com/editor](https://www.gitbook.com/editor)), plugins
([http://plugins.gitbook.com/](http://plugins.gitbook.com/)), and more ...

I don't want to hijack the current thread, Madoko seems really cool, I thought
some of you might be interested in a more established solution. I'm happy to
answer any questions !

Disclaimer: I'm one of the GitBook co-founders

~~~
bachmeier
> GitBook has great TeX support

You probably want to update your website in that case: "Markdown, books are
written using the markdown or AsciiDoc syntax. TeX support is planned."

~~~
AaronO
By TeX support I meant that we fully support TeX equations.

The website mentions TeX but means LaTeX, I'll get that fixed, sorry for the
confusion.

Our TeX support allows you basically to write Markdown/Asciidoc and use TeX
formulas wherever you need to, which gives you the best of both worlds (the
simplicity of Markdown and the power of TeX formulas).

~~~
roel_v
FWIW I still found it confusing. I think you'd better leave out the 'is
planned' part all together (just makes it seem half-finished), and instead
replace that with 'TeX equations are fully supported.'.

------
gkya
Emacs' Org-mode is pretty good for writing articles. It can be configured to
use whatever package / setting one wants while exporting to tex / pdf, e.g.
use some .sty files (presumably, I haven't needed them yet), or use the beamer
class to make a slideshow. It can be integrated with the ESS package so that
it can be used as a live programming environment for R, or whatever else the
package supports. And it also supports todo lists, agendas, and any sort of
note-taking from the first moment.

Example config for latex export (although I do not write academic articles):

[https://github.com/cadadr/emacs.d/blob/c81ff8afa3ca4ab553013...](https://github.com/cadadr/emacs.d/blob/c81ff8afa3ca4ab553013c0e5151c3595391aedb/gk/gk-
org.el)

~~~
bachmeier
I wouldn't recommend org-mode for writing professional documents. It is more
unstable than any other major piece of software I've used. I use it daily, but
not for writing. Things get changed in each release, the documentation is
rarely in sync, and in a lot of cases major changes are not documented at all.

I learned the hard way. I wrote some presentations using org-mode. Then they
changed the exporters without updating the documentation. It would be
especially problematic to write an academic article in org-mode, because you
might have to return a year or two later, and that's not when you want to find
out how much has changed since you last worked on the paper.

~~~
gkya
One can keep the intermediary .tex files should they export to pdf. Or for any
substantial project one can fix the version of org, as other projects do so
with the versions of the compiler or of the libraries. Still, if you are
correct, then it is a problem for every user. I haven't encountered such
problem in my use, although my use of ox-latex has been rather superficial
(some homeworks, a tiny CV).

------
decasia
Site seems to be offline, but in addition to what talles mentions, there's
these:

[http://madoko.codeplex.com/](http://madoko.codeplex.com/)

[http://research.microsoft.com/en-
us/um/people/daan/madoko/do...](http://research.microsoft.com/en-
us/um/people/daan/madoko/doc/reference.html#sec-performance-and-license)

[http://webcache.googleusercontent.com/search?q=cache:azgHiPZ...](http://webcache.googleusercontent.com/search?q=cache:azgHiPZpp2MJ:https://www.madoko.net/+&cd=1&hl=en&ct=clnk&gl=us)

~~~
talles
Actually, it was my mistake, it's
[https://www.madoko.net](https://www.madoko.net) (it's not working without
www).

Could someone correct it?

~~~
sctb
Thanks! We updated the link.

------
michaelmior
> Can I write my academic paper, manual, book, thesis, etc. in Madoko instead
> of LaTeX?

For me a strict requirement for this is that I can use a particular template
and document class. Unfortunately I don't have any choice as to what the
particular format is. It's not clear if Madoko makes this possible.

~~~
twblalock
This is the problem if you want to publish. A lot of journals want .docx or
Latex files, not PDFs, and they will simply reject submissions that don't
comply with their requirements.

It would be nice if journals would accept Markdown, but frankly I don't expect
that to happen anytime soon.

~~~
jahewson
Personally, I've never encountered a journal that wanted a LaTeX file. Always
the PDF.

~~~
michaelmior
I've had journals ask for both. However they claim to only use the LaTeX file
as reference in case there are issues in typesetting. In any case, it's still
necessary to produce a LaTeX file in order to use the LaTeX template.

------
JohnHammersley
It's interesting seeing the different approaches to combining the power of a
structured formatting language with the ease of use of a (relatively code
free) text editor.

I'm one of the founders of Overleaf [1], and we've taken the route of keeping
the full power of LaTeX there for anyone that needs it, but providing a 'Rich
Text mode' [2] overlay for those who prefer a less code-like experience. If
you give it a try, let us know what you think!

[1] [https://www.overleaf.com](https://www.overleaf.com)

[2] [https://www.overleaf.com/blog/81](https://www.overleaf.com/blog/81)

~~~
Phemist
I wrote my master's thesis in overleaf about a year ago, because my laptop was
starting to break down and I needed a solution that allowed me to easily
switch between university computers without having to constantly set-up my
workspace on each individual PC. That was before the rich content editor was
implemented, but I loved the experience nonetheless. The whole thesis was,
next to my research, an exercise in cloud-based software. VM's on Cloud9, Code
repo on github and my text editor on overleaf. Thanks a lot for making it
available to a poor student like me!

~~~
JohnHammersley
Thanks, that's great to hear! :) I'm impressed you used your thesis as a
testbed for cloud-based software, hope it didn't cause any/too much additional
stress! If you generated any datasets during your work, you may also want to
check out figshare[1] as a handy data repository.

[1] [http://figshare.com/](http://figshare.com/)

(Note - we work in the same office as figshare, so this is probably a biased
recommendation!)

~~~
Phemist
Thanks for the link! My thesis was basically a data analysis project,
improving on work my supervisor did prior to me starting my thesis. Figshare
is good to keep in mind, but I don't think I'd have had much use for it, as
the whole point of my thesis was to get certain figures within a reasonable
time.

I actually had quite a lot of fun figuring out how to get everything working
in the cloud. Set up my home desktop as my personal computer "cluster" (i5
processor, so a cluster of 4 cores!), I find it hard to work in an environment
that I tend to do other stuff besides work in. Derived a small representative
dataset from the massive one I had to quickly iterate over my analysis scripts
in Cloud9 (while having github take care of my revision history). Then ssh'ing
into my desktop PC whenever I needed to run the scripts on the full data set.

I considered adding a section on open science and cloud-based software to my
thesis, but in the end decided not to due to a lack of time. Open science is
based on open source principles, where everything that can be shared should be
shared. The Cloud VM angle is quite interesting in this sense, as being able
to share the machines that software for a research project was ran on is often
quite difficult (or nigh impossible), and a cloud-based VM seems to bridge
this gap somewhat. In theory, anyone could log-in to the VM and play around in
the workspace I set up for my thesis project, not that many would want to I
suppose.

------
talles
By the way, I came to find Madoko while researching for Koka (it's written in
it):
[https://news.ycombinator.com/item?id=10131071](https://news.ycombinator.com/item?id=10131071)

Also, there's this presentation:
[http://research.microsoft.com/apps/video/default.aspx?id=238...](http://research.microsoft.com/apps/video/default.aspx?id=238813)

------
rayalez
To achieve the same functionality on my blog I use:

\- Pelican - static website generator, like Jekyll but in python.

\- MathJax to render Latex

It is easy to synchronize Pelican with dropbox or github, and it is incredibly
convenient.

You can use this article:

[http://technivore.org/posts/2014/01/03/blogging-with-
dropbox...](http://technivore.org/posts/2014/01/03/blogging-with-dropbox-and-
pelican.html)

To configure it in such a way that all the updates happen automatically.

For example I can simply write an article in Editorial on my iPad, and it gets
immediately published/updated, without me having to do anything at all,
exactly zero mouse clicks.

------
phelimb
There's also "paper-now" which uses Jekyll Now + GitHub Pages.

[https://github.com/PeerJ/paper-now](https://github.com/PeerJ/paper-now)
[https://peerj.github.io/paper-now/](https://peerj.github.io/paper-now/)

~~~
tjohns
I hadn't heard of paper-now. I really like what they've done with the sidebar.

My only complaint is that I'd imagine reading academic articles in an ultra-
thin sans-serif font might get tiring after a while.

------
shadowfiend
For what it's worth, there's also `asciidoc` and its implementation
asciidoctor ([http://asciidoctor.org](http://asciidoctor.org)). It has an both
official JVM and JS packages in addition to the Ruby version, as well.

Notably missing is math support, however, because rather than Madoko's
approach of using LaTeX and then using a LaTeX-to-HTML renderer, asciidoc
renders directly to HTML (or Docbook, or LaTeX). IMO, the end result doesn't
necessarily look like an academic article placed on an HTML page… But it's
nicer for consumption in a browser—the whole asciidoctor site is generated
from asciidoctor.

EDIT: this means asciidoc is a better fit for documentation, in book or
article or whatever form—but I think once it gains math support (which they're
working on) it would be quite useful for this as well.

~~~
krapht
I don't understand what you mean about lacking math support. I am writing math
exercises using asciidoctor right now, as it integrates with Mathjax.

I would highly recommend asciidoc over markdown for scholarly work in succint
plain text. Markdown is limited in its capabilities by design, as evidenced by
all the different flavors of Markdown extension. It's what I would use to
write an e-mail or blog post. Asciidoc, in the design of the language,
anticipated extension and post-processing and has better support for using it
as part of a complete document processing toolchain. After all, it's just
syntax sugar for DocBook XML.

------
michaelmior
> The editor has ‘hick-ups’!

I'm not sure if this is a joke I'm missing, but "hiccups" is the spelling of
the term referring to involuntary inhalation as well as (informally) a minor
difficulty or setback[0]. A "hick" is an unsophisticated person[1].

[0]
[http://dictionary.reference.com/browse/hiccup?s=t](http://dictionary.reference.com/browse/hiccup?s=t)

[1]
[http://dictionary.reference.com/browse/hick?s=t](http://dictionary.reference.com/browse/hick?s=t)

------
astazangasta
Or, just use LaTEX? What makes this better? Pure TeX is hardly that esoteric,
and extra power is there if you want it.

------
jordigh
Oh, wow, this could be great. LaTeX only for the math, markdown for everything
else.

What if you need to futz with margins and styles or use a publisher's standard
.sty file?

~~~
suncanon
I concur -- do any of the markdown environments listed above accept imported
.cls latex style files? Would they even be compatible?

It seems like this would be essential for writing research papers according to
a conference's template. If so, I would definitely use....

~~~
jamessb
When Pandoc converts Markdown to LaTeX, it uses a template that speciefies
what header and footer material to add
([http://pandoc.org/README.html#templates](http://pandoc.org/README.html#templates)).

You could modify the default template to use whatever style file you want.

Pandoc also supports references with a .bib file, and inserting TeX math
formulae between dollar signs.

~~~
lelandbatey
Exactly. I've been using raw markdown processed with Pandoc as my sole
document-creation tool for the past 3 years and it's worked excellently so
far. Pandoc's pretty awesome.

------
storrgie
I'm not sure if I'll have an opinion that isn't commonly shared, so I figured
I'd elucidate: I deeply love the simplicity of using markdown + LaTeX, however
I realize that I'm somewhere on the gradient of complexity where I'm
sacrificing some power for simplicity. Currently I think the tool that is used
most is pandoc, and there are some offshoots that give pandoc more 'academic'
power, like scholdoc.

I've just been hoping that the pandoc world would progress (add more scholarly
features) so that I could continue to keep my own data locally, manage it in
my own vcs, and process it with a makefile.

The only reason I see to hop on the software as a service bandwagon is for
collaborative real-time editing (and some projects benefit greatly from this).
I'll plug sharelatex for that, primarily because their model releases the
software so that you can run your own if you don't want to pay for the
service.

~~~
etherealmachine
Is Madoko a SAAS app? If so I'll note another problem - madoko.net is
currently timing out when I go to access it; any data inside is stuck there
for the duration.

On the Markdown+LaTeX note, I wrote my own Markdown parser
([https://github.com/etherealmachine/markdown](https://github.com/etherealmachine/markdown))
to drive my github.io site
([https://etherealmachine.github.io](https://etherealmachine.github.io)).
Basically it's what you describe - easy mixing of Markdown+LaTeX to construct
nice looking HTML.

~~~
dimgl
You can download Madoko and run it yourself.

[http://madoko.codeplex.com/](http://madoko.codeplex.com/)

[http://research.microsoft.com/en-
us/um/people/daan/madoko/do...](http://research.microsoft.com/en-
us/um/people/daan/madoko/doc/reference.html)

------
antman
Scholarlymarkdown is nice and I like the way you can add captions and
references to equations and images.
[http://scholarlymarkdown.com/](http://scholarlymarkdown.com/)

------
Animats
Perhaps someday there will be computer programs where you can write things
without typing in funny codes.

TeX embedded in Markdown seems painful.

How about writing in a restricted subset of HTML, as some forums (notably
Slashdot) allow? <h1>, <h2>, .., <title>, <p>, <i>, <b>, <blockquote>, and a
few others let you do what Markdown does. For math, there's MathML: Square
root of two: <math><msqrt><mn>2</mn></msqrt></math>

~~~
FraaJad
I written TeX embedded in markdown the time with Pandoc for reports and
papers. It's much easier than writing all TeX.

~~~
FraaJad
wow, what was i thinking when i wrote that sentence? doesn't make any sense.

------
anotheryou
Yet another Markdown flavor...

Markdown is really not sufficient, this markup looks very cool but I'm missing
compatibility again.

I'll see if I can make it yellow cms compatible when exporting html...

~~~
dimgl
The Madoko document states that it implements different flavors and extends it
slightly.

> Madoko is fully compatible with basic Markdown syntax and passes the entire
> test suite. It also implements most extensions, like Github flavored
> markdown, PanDoc, Markdown Extra, and multi-markdown, and it adds quite a
> few features itself to make it really useful for writing academic and
> industrial documents.

------
coliveira
Good try, but in fact it is useless to use something other than Latex to write
academic articles. Most journals in mathematics and engineering accept Latex,
but I have never seen one accepting markdown. Which means that you will have
to convert to Latex source anyway -- and in many cases make sure that the
Latex code uses the style package of the publisher. This seems to me just to
be asking for more trouble.

------
mpnordland
For School most of my papers require MLA formating. I found a mla latex
template and so now I just use pandoc and that template to do my papers. When
they want a docx I also made an odt template that I the use libreoffice to
convert to docx. If madoko had an option to do that, then I'd be interested,
otherwise it's no use to me.

------
mhartl
Softcover [1] covers many of the same bases as well. Actually supporting all
of LaTeX's features in HTML is basically impossible, though, so no matter
which tool you use it's best to go in with tempered expectations.

[1]: [http://www.softcover.io/](http://www.softcover.io/)

------
cetra3
We use a simple md2pdf script internally that takes a markdown, throws on the
company logo & font, and produces a pdf document.

Process is md (vim/mou) -> cmark -> wkhtml2pdf -> pdf

This works well for us, but would be nice if we could sort of merge this with
an online wiki of some sorts.

~~~
creshal
Have you considered pandoc? That allows to reduce it to md → pandoc → pdf, and
in my experience pandoc generates much better PDFs (working links, etc.)

------
SZJX
Doesn't org-mode already a kind of do that? I think it will handle most of the
requirements just fine, handle LaTeX when necessary and what's better is that
it comes within emacs allowing all kinds of easy customizations and
extensions.

------
davidcollantes
Typora ([http://typora.io/](http://typora.io/)) does similar, but it is an OS
X application (Windows coming, so the author says).

~~~
dimgl
Can you do LaTeX on Typora?

~~~
davidcollantes
It can! See
[https://twitter.com/Typora/status/637495313259892740/photo/1](https://twitter.com/Typora/status/637495313259892740/photo/1)

------
Avshalom
Well the html rendering is quite nice but Markdown is so limited it seems like
you're just writing latex with '['s replacing some of the '('s.

------
sampo
> Madoko also automatically synchronizes your changes to the cloud storage
> every 30 seconds or so.

Does it make a new push to GitHub every 30 seconds?

------
dllu
A few months ago I created my own Markdown-like lightweight markup language
supporting LaTeX equations, which can be compiled to either HTML or LaTeX:
[http://lawrence.lu/programming/dllup/](http://lawrence.lu/programming/dllup/)

------
mangecoeur
Not sure how this is really different from pandoc markdown...

------
anotheryou
pfew, but the generated html is ugly (missing breaks, strange inline styles
and classes)

------
jbssm
This is really nice. Does it allow to work on multi file documents? i.e. when
wiring a big document like a thesis, it's nice to have the chapters divided by
different files.

