Hacker News Reader

Comment by drhayes9 | Hacker News Reader

I've been starting to suffer from Markdown fatigue and investigating tools that support RST or asciidoc. I wonder if this system might support those tools in the future?

View on HN

Asciidoctor has a plugin for Jekyll you might be interested in: https://github.com/asciidoctor/jekyll-asciidoc

The readthedocs engine is RST friendly. Personally I prefer documentation that's easy to write and RST is not that.

I admit, I haven't tried to write a lot of RST or asciidoc beyond playing around with it. And it's a good point -- docs that are hard to write don't get written.

Any reasons for the markdown fatigue?

Having used a lot of markdown and reStructuredText, I can see the arguments that the lack of common standards in markdown is a huge pain. There's still a lot of variety between markdown implementations and while Common Mark and open GFM standards are helping to a point, you still can't always count on a markdown engine to have things as basic as definition list support or HTML anchor support (linkable ids for sub-headings), and there are still some weird subtle implementation differences in those things.

There's also a lot to be said about the way that reStructuredText provides standard plugin spaces in the markup. While it may look over verbose at first glance, it is a great thing when you start to pick up that a lot of reStructuredText is based on the same plugin markup and there's a consistent way to work with new plugins. Something like that could be hugely useful to Markdown, and probably could have stymied some of the complications in standardizing things like Common Mark and GFM had that consideration been baked in from early on.

Most of Markdown is great for me and feels natural. Headings, bold, italics, lists -- those are all great.

Examples that don't feel natural are image syntax, dropping down to HTML for unsupported features (pre-supposes output format), emphasis on presentation vs. semantics, the various flavors of writing tables, etc. How do I write an index? A table of contents? Any way to differentiate a footnote or an aside from a basic link?

YAML front matter is a great ad hoc standard for including metadata about a document within the document. It would be great if the various flavors of Markdown standardized on that, too.

I've started work on an evolved markdown version called text with instructions (.texti) [1]. Anyways, what's broken in markdown? The image links are ugly e.g. ![](fail.gif). Why not {{pic.gif}}? Almost everybody incl. Wikipedia markup is using = for headings e.g. =Heading 1=. Why not also in Markdown? Another good reason is that # is the "universal" comment marker in the unix world. If you mix and match yaml front matter / back matter (meta data) with comments - why not use the same comments? Did you know - there are no comments in markdown. And so on and so on. It's time to fix (evolve) markdown. Cheers.

[1] More at -> https://texti.github.io

You could use Pelican (getpelican.com) -- it's an SSG that supports Markdown and RST and asciidoc and is generally extensible.

Pelican is great for blogs. I don't know that I'd suggest it for a "Knowledgebase".

I wonder also, gitbook-cli supports both md and adoc. Asciidoctor is easier to write and you don't have to use its advanced features for it to become superior to Markdown.

== What is easier to write?

// adoc comment

== What is easier to write?

image:adoc-foo.jpg[link="http://foo.com"]

== What is easier to write?

1. first md - no auto numbering

2. second md - no auto numbering

3. third md - no auto numbering

. first adoc - auto numbering

. second adoc - auto numbering

. third adoc - auto numbering

What is easier to write?

[Get the PDF]({% raw %}{{ site.url }}{% endraw %}/assets/my-md-file.pdf)

link:{ctx_path}/assets/my-adoc-file.pdf[Get the PDF]

> . first adoc - auto numbering

That looks like a bullet to me. How do you differentiate unordered and ordered lists?

Also, markdown auto-numbers too, so you can just prefix every item with `1` if you'd like.

> so you can just prefix every item with `1` if you'd like.

oh, didn't knew that, use asterisks instead of dots is for bulletspoints in asciidoc. For unordered lists use more than one asterisk (HN breaks my example here), look at this example http://www.methods.co.nz/asciidoc/chunked/ch17.html if you mean Implicit numbering

You could also do:

[start=5]

. nr-5

. nr-6

. nr-7

Reply on news.ycombinator.com