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/...)
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 !
This reinforces some ideas that have been percolating in my brain for about two years. Between Gibook, PollenPub, and now Madoko it is now apparent that for the first time in its existence LaTeX is getting some competition.
What LaTeX gets right is that it produces beautiful structured academic-type (references and figures and such) documents. What it gets wrong as Gruber's Markdown has shown us is that the basic units of text should look like text and trigger markup through whitespace and intuitive but ultra-minimal markup such that without a processor it looks like an anally retentive writer produced the document. It codifies ascii practices. It's one of those ideas that until it happens you'd never think of it but afterwards you're going, "of course!". Besides Python and Markdown, do any file formats work this way?
I'm not going to make a Steve Yegge type predication but if I were I'd say that some form of scholarly markdown with multiple toolchain implementations (with git integration) is going to oust LaTeX as the structured document tool of choice. Be interested in what others have to say on the matter.
One of the basic tenets of TeX and LaTeX is stability, Maths has a very long shelf life! You can TeX Knuth's papers from 30 years ago and they will still produce the same output. If I were to spend 3-5 years on writing a PhD Thesis the investment in learning LaTeX is minimal compared to the rest of the effort. With a new extended markdown markup, you will still need to learn a new syntax and LaTeX markup for example if you wanted to include TikZ code.
TeX and friends has adapted over the years through external tooling, without changes to the core, for example moving from postscript to pdf, the new engines XeLaTeX and LuaTeX. Madoko is just a preprocessor for LaTeX. If you had to finally do some changes to the LaTeX code it produces it will be very difficult as this LaTeX code is not very clean.
Having said this though Madoko and similar projects are great for the LaTeX community, as an entry point to newcomers and to occassional users. It is a great Project especially as is written in Koka in itself a beautiful Project.
+1 for Madoko as it's free and Gitbook is not. I can use Madoko to create and publish my content and keep 100% of the income unlike Gitbook that takes a cut.
He didn't seem to be arguing against the principle of charging for the service. But, from a user's viewpoint, having to pay for something is rarely an argument in its favor.
It's called "trying to capture more value than you add." Seems to be a key idea behind many SaaS/PaaS startups these days. Not an indicator for long-term success.
Well that's a judgement call for the user choosing the service. If they think the value is there, they will pay. That's how capitalism works, and I daresay if Gitbook had it wrong, they'd have given up by now.
What experience do you have with Gitbook to deem that it doesn't add enough value to deserve the payment?
How does your tool handle cross-references to #include'd pages? I have some home-grown tools that basically use a C++ preprocessor to assemble one big Markdown file from per-chapter or per-section chunks. What I struggle with (to do elegantly) is having robust cross-references, and to keep header levels consistent (e.g. when you include a section that itself has headers inside a h1 or inside a h2, you'd want the section's headers to become h2 or h3, respectively).
Do you have any support for reviewing, in a way similar to Word's 'Review' (comments and tracking addition deletions)? Using version control and branches is not OK, because non-software people cannot wrap their heads around it (just getting them to write in anything but Word is already a big enough hurdle...)
Do you have a proposed workflow to work with formulas? Inline TeX (or LaTeX) is again a no-go, it's too finicky to get right for people who don't have Edit/Compile/Preview Stockholm syndrome (bitter? me? nah). What I'd settle for is a separate file for each formula, and a graphical editor that can edit those files. A somewhat convenient desktop-based editor that'd give an overview of everything would be better (so having some way to start EqualX from your desktop tool would be enough).
All books are stored as git repositories so you get branching, history, etc ... out of the box.
We have great GitHub integration because it's the main Git host out there, we store git repos too.
If we shutdown, our toolchain and book format is already open source (https://github.com/GitbookIO/gitbook), so no matter what you'll always be able to use that to build your book locally. Secondly our Desktop Editor (https://www.gitbook.com/editor) works offline so you could even continue to use that. And well since your book is a git repo, you can have a local copy, a copy on GitHub or any other git server of your choice. So I think you should be good :)
We don't believe in vendor lock, we're big supporters of open-source and we want users to use our tools and platform not because they're obliged to, but simply because it's the best workflow/product for them.
See also RMarkdown. It also has very good support for TeX equations, plus inline R code, and it uses Pandoc behind the scenes to handle multiple ouput formats (even .docx!) as well as bibliography. The big caveat for now is poor support for internal cross-references.
Love this idea, might copy my current novella on the web (http://www.flailfast.com/) over to your platform to see how it looks. Out of curiosity: any chance you guys might integrate bitcoin donations/payments in addition to USD?
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).
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.'.
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):
I would highly recommend org-mode for writing documents and papers. I'm an academic, and have been using org-mode for the last 4 years as part of the paper writing process.
One of the best features of this pipeline is the fact that I can write a large chunk of the document whilst conducting research. I can jot down notes, caveats, schedule TODO items etc. and just tag the bits I want for my own reference as 'noexport', so that they don't make it into the exported tex or pdf document.
Another great feature is that I can embed code for producing tables/figures all within the document and specify whether I want the code or result or both to be included.
Finally, once I am happy I have most of the document the way I want it, I export to tex to deal with the final tweaks to finesse things -- spacing for the entire document, fine-grained adjustment of figure formatting.
This ensures that I have all the information that went into constructing the document and allows me to deal with various venue-specific constraints like submitting a source archive, or pdf as necessary.
Here are some resources for getting started with this:
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.
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).
It's true that org-mode is a bit of moving target, but the basic syntax for document formatting doesn't change. If you are really worried about this you could record/archive which version of org you used to put your paper together.
> 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.
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.
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.
Do you mean for review, or even when they've accepted and ask for a camera-ready version? I always assumed all publishers need the source so they can do the small tweaks they do.
[OTOH, I've seen claims many publishers already have a process for publishing Word submissions — something involving monks spending their lives typesetting everything from scratch? — and so when they do get a nice LaTeX, they throw the source out re-use the above process! Perhaps that was only about the bibliography though.]
I've seen some Springer (LNCS) submissions, and those definitely included the .tex source.
arXiv requires the source, mainly so they can re-compile them in the future with better tools [https://arxiv.org/help/faq/whytex]. Unusually, they make sources available for anyone to download.
Earlier this year, I needed to upload the LaTeX file and it needed to be written with the journal's template. In order to specifically fit into the journal's guidelines, the template was sent to some editing contractor where some minor changes where made to the source, e.g. "eq." to "Eq.".
As far as I know, a lot of the journals have their own automated build systems for the manuscripts to perfectly fit into their designs.
Nevertheless, I've also encountered PDF uploads. But even then, the PDF will be automatically checked for consistency.
I believe most (all?) Elsevier journals require the LaTeX source, so you upload the .tex, .bib and any images etc. to their EES wepage, which compiles the PDF there.
One of the problems with accepting Markdown is that your work will still likely be formatted as a PDF and if you submit Markdown, you don't really know what that final output is going to look like. At least not without a lot of extra tooling on the part of the publisher.
Even if your journal accepts PDFs, michaelmior's comment raises an important issue that a LaTeX style template cannot be imported into most (or all?) of these Markdown editors. This would be a great feature to add, IMO!
The issue with that is that a LaTeX template is turing-complete. Doing a meaningful import of arbitrary journal styles without re-implementing TeX is a very, very, very hard problem.
> Even if your journal accepts PDFs, michaelmior's comment raises an important issue that a LaTeX style template cannot be imported into most (or all?) of these Markdown editors.
Perhaps it would be easier to go the other way -- to modify a Markdown parser to output a simple subset of Latex that can fit into most common academic templates.
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!
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!
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.
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.
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.
For what it's worth, there's also `asciidoc` and its implementation asciidoctor (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.
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.
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].
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).
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.
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.
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.
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.
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>
MathML is not a full replacement for TeX, and if we are talking about actual publication of papers/books rather than web content then neither HTML nor MathML are really up for the job.
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.
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.
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.
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.
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.)
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.
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/
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.
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/...)
The format and toolchain itself is open-source (https://github.com/GitbookIO/gitbook)
There's a ecosystem built on top of that such as a Desktop Editor (https://www.gitbook.com/editor), plugins (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