Thanks, this is exactly what I was looking for. A simple syntax for documentation that is extensible with macros. I am glad AsciiDoc includes them, they are very useful.

I love AsciiBook. Everything but the name. If we ever get an amazing collaborative development tool like Github that has built-in AsciiBook rendering, this project would have been called "Scholarly AsciiBook (but we got Unicode support too I swear really)".

Edit: I was wrong about Github not supporting AsciiDoc

Github does render asciidoc using asciidoctor. What is missing in that that is possible in Markdown?

Well, I did not realize Github has had AsciiDoctor integration for two years now (I've been doing most of my scientific work in GitLab during that time). I retract that comment and regret the error. Hopefully they add it to Github pages some time soon.

To be honest, there was never really any conscious decision to pick Markdown over AsciiDoc. It was just serendipity that when I was looking to convert a bunch of my existing Markdown notes to papers, John happened to add (at Martin Fenner's urging) pretty robust support for citations to Pandoc. Being able to use an existing .bst files and Natbib author/year syntax with existing Bibtex database files, while also using CSL to format to everything else was pretty key. The syntax only worked in Markdown at the time, so I went with that. This project just simply grew into an experiment on how to get the least hack-y looking source document for what I needed.

Basically, I had a bunch of existing Markdown stuff typed with both my phone and my computer using NValt (already using the double-backtick math syntax as a hack), and I was looking for a way to reuse all that. If I had to do conversions or had to start from scratch, I would have just started another LaTeX Document, and then this project wouldn't be here.

As an aside aside: I personally think that one shortcoming of AsciiDoc is that Markdown ended up having a more mature application ecosystem outside of the most general purpose text-editing tools. I'm thinking of something like Scrivener/Ulysses which is really great for project writing and has robust markdown support while writing. I've also recently found out that TeXpad "mysteriously" formats Markdown syntax in the editor, and builds an in-editor TOC of it. This is in addition to with rendering support in basically every note-taking tool. Sadly AsciiDoc doesn't seem to have experienced a similar growth spurt in terms of popularity amongst developers, and as a result have a bit more friction to use.

Yeah. Unfortunately asciidoc isn't as popular as markdown and the ecosystem is small. I never paid much attention to asciidoc until I read this blog post - https://medium.com/@chacon/living-the-future-of-technical-wr... and realized that I have experienced many of the same frustrations with markdown. I tried out asciidoc and became a convert :)

For live preview of asciidoc there are some options - http://asciidoctor.org/docs/editing-asciidoc-with-live-previ.... Among them Atom with live preview works really well.

Just wanted to mention that GitLab supports asciidoc https://github.com/gitlabhq/gitlabhq/pull/7569

Thanks for the heads-up. I'm going to bug our admin again to upgrade.

Great! :)

fyi asciidoctor allows using markdown syntax inside your asciidoc file.

citation: http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/...

In addition to supporting previews of AsciiDoc files, you’ll find that GitHub also does the “rendered prose diff” trick for commits and pull requests that include changes to AsciiDoc files.

AsciiDoc is a nice project, but I think that pandoc's variant of Markdown has a lot of advantages over AsciiDoc for academic writing. Let's just compare support for math and citations, for example. Pandoc's citation support is output-format independent: you can write the citations, specify a CSL stylesheet and bibliography, and you'll get the same output in every format pandoc supports. In AsciiDoc, as I understand it, if you want automatic citation support you need to use LaTeX, and then you're limited to output in LaTeX and PDF. Similarly for math: pandoc actually converts your LaTeX math to MathML (for formats that like that) or to native Word equations (for docx); in AsciiDoc, as I understand it, your LaTeX math will work if you target LaTeX, but if you want MathML you need to put MathML in the source. If you want to target both, then maybe you need two different source documents?

I don't have much experience with AsciiDoc, but I've encountered other limitations in writing pandoc's AsciiDoc renderer. For example, I didn't see any way to include multiple paragraphs (or other block content) in an AsciiDoc footnote. That's a deal-breaker for many academics.

I also want to emphasize something that is often not mentioned in comparisons of Markdown and AsciiDoc. As John Gruber emphasizes in his Markdown documentation, Markdown emphasizes ease of reading in source format. AsciiDoc has different priorities, and it sacrifices the readability of the source document to get them. Here's an example involving nested lists, from the AsciiDoc manual:

    1. List item one.
    +
    List item one continued with a second paragraph followed by an
    Indented block.
    +
    .................
    $ ls *.sh
    $ mv *.sh ~/tmp
    .................
    +
    List item continued with a third paragraph.
    
    2. List item two continued with an open block.
    +
    --
    This paragraph is part of the preceding list item.
    
    a. This list is nested and does not require explicit item continuation.
    +
    This paragraph is part of the preceding list item.
    
    b. List item b.
    
    This paragraph belongs to item two of the outer list.
    --

Markdown equivalent:

    1.  List item one.
    
        List item one continued with a second paragraph followed by an
        Indented block.
    
            $ ls *.sh
            $ mv *.sh ~/tmp
    
        List item continued with a third paragraph.
    
    2.  List item two continued with an open block.
    
        This paragraph is part of the preceding list item.
    
        1.  This list is nested and does not require explicit item continuation.
    
            This paragraph is part of the preceding list item.
    
        2. List item b.
    
        This paragraph belongs to item two of the outer list.
    

Note that the AsciiDoc is at least as easy to write, perhaps easier, because you don't need to worry about indentation. But the Markdown source is more readable; the indentation makes clear the structure of the list in a way that mirrors how it would be displayed in a browser or on the page.

The CommonMark is definitely more readable, but Markdown is just so sparse by design that every time I tried to use it for anything more serious than e.g. a blog post I found myself banging my head against the wall, so it's a tradeoff I'm happy to make - and we're talking about languages whose purpose is to produce readable output, so while a readable source file is definitely a nice thing I think it's hard to make a case for valuing that over functionality. To title a paragraph in markdown you can choose from an <h[1-6]> or a <strong>, that's it, and it's so tightly coupled to HTML (it's more of an HTML generation format like HAML than a document format really) that if you need to do anything remotely complex you're forced to either inline the HTML or bind yourself forever to external tools - in which case the goal of universal readability is defeated anyway.

Markdown's syntax constrains how much it can ever do, whereas AsciiDoc is designed to be extensible, providing macros at the "language" level and underneath that there's the whole DocBook toolchain: it seems to me that the clever move is leverage all this, rather than create yet-another-Markdown (and it's not like the syntax tradeoff is at all dramatic.) I think the footnote issue you mention can be done in block macros, but I'm not sure.

I might be getting a bit utopian here, but what would be really great is if all these markup languages sought to have their canonical implementation in pandoc, which would allow for the standardisation of a set of pass-throughs/filters/annotations for things like equations and citations.

Thanks for pandoc, btw. Just out of interest, is there a reason you haven't attempted an AsciiDoc reader? (Or have you?) Assuming it'd be quite a bit more work than the others, what with macros and so forth.

See https://github.com/jgm/pandoc/issues/1456.

Markdown (even this Scholarly Markdown) is a non-starter for me. It doesn't seem to support individual equation numbers for aligned equations. Plus, Scholarly Markdown oddly decided to put them at the beginning of the line rather than after. Why? The equation is more important than the number so it should be first. Plus, it's nice to have the numbers all aligned to the right margin.

You stated about the footnote support being a deal-breaker for many academics, the poor equation support is a deal-breaker for me. Most of what I write is full of equations, especially aligned equations. It's necessary to reference a specific equation that might be on a different page (or far above it on an HTML page).

It looks like Asciidoc has different ways of handling LaTeX equations for non-LaTeX output. It can render a PNG, it can use a Javascript solution, or it can output MathML.

I really want to address the math support, because I work with a lot of mathematicians, and one of my main goals is to support most of the latex AMS math features we're used to (as much as MathJax can support outputting on the HTML side anyways), and of course that includes aligned equations. In fact one of the first things I did was to figure out how to support multiline equations.

Turns out, you just need to write consecutive expressions one after another. Put ampersands in all these consecutive expressions and ScholarlyMarkdown will turn it into one giant align environment. If there is no ampersands, it generates a gather environment instead.

I apologize for this not being in the documentation. After all, I estimate that it is only about 30% complete. It really is in a dismal state. I originally didn't expect much people to see the site until later this year when I plan to launch it. This will all be rectified eventually, promise!

Here is literally a large align-block example straight out of the thesis that I'm currently busy working on (instead of the documentation). You can inspect the Scholdoc-rendered LaTeX code to see that you can really do align blocks reliably with this syntax.

http://goo.gl/9lErxa

If you output to HTML, it will just turn this same align block into a MathJax-friendly format, and hand it off to MathJax for rendering. This is what it will look like:

http://jsfiddle.net/hzvwa139/3/

Where the equation numbering is place is entirely a non issue. Why? It's not being decided by ScholarlyMarkdown, but by MathJax. Go to the jsFiddle example above and change the line that reads

  TagSide: "left",

To now read

  TagSide: "right",

and you get it now on the left. Scholdoc simply put those default setting there for convenience; you're not tied to it at all.

Why put the number on the left side by default? Think of what happens when you have a long equation, and when you're trying to read it on a narrow screen such as a phone. If the number was on the right, it may very well be cut-off by the screen, forcing you to scroll around to find equations. Sometimes layout decisions that made sense for paper for centuries doesn't make sense for screens.

I should point out that Scholdoc is only using MathJax on the HTML side for consistency; there is no technical reason why it can't use another renderer that understands LaTeX, but so far MathJax is the only one that even comes close to supporting all standard AMS features. Note that MathJax itself does HTML/CSS, MathML, SVG, and PNG (via a node server) output, and is entirely user-configurable.

I still think equation numbers on the left is a mistake. Ideally, for smaller screens it would split across multiple lines. Or, it could choose the positioning based on screen size.

For me, MathJax can't render my equations. I use some techniques to get a vector with an arrow on the bottom. Two commands I used all throughout my thesis are:

  \def \rV#1{\hbox{$#1$\kern-0.38em\lower0.85em\hbox{$\vec{}\,$}}\,}

and

  \def \Vec#1{\hbox{$#1$\kern-1.0em\lower0.4em\hbox{${\scriptstyle \rightarrow }$}}}

These won't work in MathJax (understandably).

> Ideally, for smaller screens it would split across multiple lines.

C'mon, nobody deserves to be subject to automatic TeX expression breaking. Even careful hand-tuning with help from the breqn package can often look pretty bad.

> Two commands I used all throughout my thesis are:

At the risk of turning this into TeX StackExchange, I just want to point out that these kerning manipulations are entirely possible in MathJax. The problem is that, maddeningly, they chose to have non-math commands like kern and lower work exclusively in math mode, and not outside one like in a hbox. Therefore, if you change your second command to something like this:

  $a \kern-1em\lower0.4em\hbox{$\scriptstyle \rightarrow$}$

then it will work in MathJax. Of course, this would then break in regular TeX because you're not supposed to use kern and lower in math mode. I keep myself sober by remaining optimistic about a potential overhaul in the MathJax latex processing code.

In the meantime, I think we would benefit from a stopgap service that renders these things in an actual TeX engine running on a server into high-res PNG (easy) or SVG (doubtful). There's been quite a resurgence in effort to make latex rendering into a scaleable web service lately. I'd love to collaborate with someone from, say, ShareLaTeX on that, if possible.

That's awfully annoying of MathJax because you need two separate versions of the LaTeX, one for MathJax and another for LaTeX output.

I know that there's dvisvgm for SVG output from DVI. I think there's also a tex2svg. Also, there's LatexRender-ng. So, there's a number of tools for SVG output.

I have yet to see a good stylesheet for AsciiDoc's DocBook output for creating a decent PDF. Do you have recommendations? I love AsciiDoc, but am only using it to generate HTML right now.

As @jauco said try Asciidoctor - http://asciidoctor.org/

In addition to default asciidoctor style, there are other themes available - http://themes.asciidoctor.org/preview/ (See bottom right for theme switcher).

You can also take a look at Pro Git book styles - http://git-scm.com/book/en/v2 which was written in asciidoc - https://github.com/progit/progit2

Thank you so much for the pointer to the git-scm-book (in the context of asciidoc/pdf output etc). Sadly the pdf-version, isn't exactly well laid out. It suffers from similar issues that a lot of html-to-pdf-based tools (although I assume it's sgml-to-pdf in this case?) -- horrible breaks, and it also "feels" wrong wrt. some spacing/etc. Generally standard LaTeX will look (much) better than this without tweaking, IMNHO.

On the other hand, they also have an epub style sheet, and it appears (a little oddly) that the layout of the epub is better than the pdf.

FWIW most "heavily optimized" custom LaTeX styles I've come across tend to feel like being slapped in the face with MS Word -- and I think I've yet to encounter any that actually improve on the "standard" styles in any meaningful way (with possible exception of the APA style, which is ugly, but as it has to conform to APA, it's ugly by design. And looks better than most other APA conforming styles I've seen).

Still, having a starting point makes the job much easier -- so this is a great resource.

My supervisor has been writing a book (for many years now) and he has a heavily customized LaTeX style that actually works quite well for his book. He has a lot of special needs for formatting so none of the default styles really worked for him. It's actually a pretty well done dynamics textbook. I've been looking forward to the actual final published text.

You should ask him if he's considered publishing the styles under a Free/open license. Even if parts of it is very specialized, I'd surprised if it couldn't work as an interesting starting point for other projects.

Next time I talk to him, I'll see about it. I don't talk to him that often now that I've finished my PhD.

Unfortunately not, XSL isn't really my thing. I'd probably consider trying to go via LaTeX, but that's because I like the way LaTeX looks out of the box and probably isn't appropriate for most things.

Try asciidoctor and its stylesheets.

Are there any good wiki softwares that use Asciidoc?

The github wiki software supports asciidoc and many other formats - https://github.com/gollum/gollum

Any others?