Hacker News Reader

Comment by sbjs | Hacker News Reader

I really like the idea of a new markup format. To me markdown has been very unintuitive in some ways. I can never remember whether more # means higher or deeper header level. Or which of - - - or === makes a first or second level header. But since markdown is first class citizen at github, I don’t think we’ll ever be able to see any real competition rise up (even though github has first class support for others, markdown is the clear winner). And I’ve never heard anyone else mention these confusions so maybe everyone else is fine with it and I’m the only one who wants an alternative.

View on HN

I think the biggest problem with Markdown is that the spec is ambiguous and there’s no clearly prevailing standard.

Jeff Atwood tried to fix this, but the creator of Markdown does not seem keen to cooperate with any attempts to standardize it.[1]

Since he owns the trademark, standardization will likely be impossible without his cooperation. Not to come down on John Gruber, I understand his position and he’s a cool cat... it’s just an unfortunate shortcoming of markdown, which I otherwise love.

With the exception of ordered lists. I can never figure out how to get multiple paragraphs or interstitial content into ordered lists, and it always resets the counter to 1... but everything else is great!

[1] https://blog.codinghorror.com/standard-markdown-is-now-commo...

Asciidoc is a viable alternative. By now you have Asciidoctor in Ruby, AsciidoctorJ on JVM, Asciidoctor.js and even original Asciidoc Python recently rewritten for Py3.

https://github.com/asciidoctor/asciidoctor.org/blob/master/d...

Here is a very short intro on rendering in your browser: https://www.youtube.com/watch?v=4LOB3WeOUJk

Asciidoc.org at some time in the future should be the page for the language spec. The biggest feature is probably that you can produce DocBook and it's very easy!

We've been really happy with Asciidoc at work. We maintain multiple large versioned documents as a team and had been using Word and 'Track Changes' to do updates. We've now moved them entirely to Asciidoc and are using Git for tracking and approving changes, and the difference is night and day. We considered Markdown at the time, but things like numbered lists incorporating paragraphs, metadata inclusion, and the need to specify certain elements about the final published version meant that Asciidoc was a clear winner. To get all of those incorporated using Markdown would have meant implementing one of the Markdown dialects, and then ensuring that everyone's tool-chain that thought it spoke Markdown wouldn't then munge it to death.

Markdown isn't perfect, but I find it really weird that you complain about the headers in particular. I never use the underline style, but I don't think you can get more straightforward than the # notation.

I've been working on an evolved markdown format alternative - that removes some known failures such as image links e.g. ![]() and improves some such as links e.g. lets use wikipeda style links :-) and lets offer more link of syntax alternatives - and adds some stuff while trying to learn from the "real world", that is, getting the best of the world of wikipedia markup, markdown and latex all together and easy to use. The format is called texti short for text with (formatting) instructions. See https://texti.github.io for more.

You don't have to remember that - it's up to you. Whatever markup you use for headings, the levels are inferred.

Reply on news.ycombinator.com