Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Compare AsciiDoc and Markdown

docs.asciidoctor.org

Post reply on HN
Print view View original

111–120 of 137 posts

Re: Compare AsciiDoc and Markdown

#111

Post by sa46 »

sofixa wrote: post #10
taftster wrote: post #2

I really like AsciiDoc and would encourage anyone to give it a try, especially for things like software documentation (in all forms). I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL. The problem is simply that github, gitlab, and friends adopted Markdown and so…

> I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL There'd a middle-ish ground we're going with at work - you have the documentation alongside the code in git, and your CI/CD also uploads it to Confluence/whatever for less technical folks/searchability/etc. ( Too…

I really like the sound of this. That’s how Google’s internal technical docs worked. Write markdown in src repo, get nice, searchable doc site in return.

Anyone know if a tool like that already exists to turn README.md files into a website?

Re: Compare AsciiDoc and Markdown

#112

Post by sa46 »

taftster wrote: post #2

I really like AsciiDoc and would encourage anyone to give it a try, especially for things like software documentation (in all forms). I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL. The problem is simply that github, gitlab, and friends adopted Markdown and so…

The really fun part of having docs in confluence is that if Confluence goes down, you lose access to ops playbooks.

I’ve had similar fun experience with Slack-ops when slack goes down.

Re: Compare AsciiDoc and Markdown

#113

Post by 29athrowaway »

encryptluks2 wrote: post #5
29athrowaway wrote: post #3

The point of Markdown is having a very tiny set of features: headers, paragraphs, lists, links, pre-formatted text, etc. You can learn this in minutes. Having Markdown with more features is against what makes Markdown useful: minimalism.

I disagree... Markdown is no longer a single unified version. There are multiple implementation, extensions, etc. The original Markdown spec by itself isn't that useful and there is a reason so many extensions have been made for it. It can maintain simplicity while still adding new features. Pandoc has some great examples of Markdown extensions that are really useful.

There are dialects of Markdown but they all respect the core features.

Re: Compare AsciiDoc and Markdown

#114

Post by sofixa »

sa46 wrote: post #111
sofixa wrote: post #10

Earlier quoted context omitted.

> I very much despise the trend to write sharepoint or wiki/Confluence pages as a means for software documentation. I want my documentation to reside next to my source code, not at some obscure corporate URL There'd a middle-ish ground we're going with at work - you have the documentation alongside the code in git, and your CI/CD also uploads it to Confluence/whatever for less technical folks/searchability/etc. ( Too…

I really like the sound of this. That’s how Google’s internal technical docs worked. Write markdown in src repo, get nice, searchable doc site in return. Anyone know if a tool like that already exists to turn README.md files into a website?

There are a few ones, the only one that comes to mind is Docusaurus from iirc Facebook.

Re: Compare AsciiDoc and Markdown

#115

Post by blacktriangle »

mikl wrote: post #108
blacktriangle wrote: post #106

Earlier quoted context omitted.

I'm not a Gruber fan but I think his actions in this case are totally defensible. Every month on HN there's a post about some OSS project mod stepping down due to abuse and insane expectations from the community. Gruber wrote a tool that solved his own personal problem, shared it with the world because why not, and then made damn sure he wasn't going to have to deal with any fallout put on him for his sharing.

Gruber did the exact opposite than stepping down. Even now, he insists on controlling the name “Markdown”, despite having abandoned the project over 15 years ago. It would be a bit like Tim Berners-Lee trying to police how people use “WWW” today. He might theoretically be within his legal rights, but he’d still be a jerk for doing so.

So then name it something else than Markdown? Gruber invented and published it, its fair that he gets to protect the name.

Re: Compare AsciiDoc and Markdown

#116

Post by hutrdvnj »

baby wrote: post #36

I just wrote an entire book in asciidoc and honestly I don't like a lot of the decisions and the syntax, the tooling is also quite messy and hard to use/configure. Having said that, I'm not sure if there's really any alternative. If you need the extensibility and diff-ability of asciidoc, then you're probably going to have to use it. If you don't need it, stick with markdown. EDIT: so that people get an idea, I use a…

What tools are you using to write a book in asciidoc?

Re: Compare AsciiDoc and Markdown

#117

Post by mikl »

blacktriangle wrote: post #115
mikl wrote: post #108

Earlier quoted context omitted.

Gruber did the exact opposite than stepping down. Even now, he insists on controlling the name “Markdown”, despite having abandoned the project over 15 years ago. It would be a bit like Tim Berners-Lee trying to police how people use “WWW” today. He might theoretically be within his legal rights, but he’d still be a jerk for doing so.

So then name it something else than Markdown? Gruber invented and published it, its fair that he gets to protect the name.

Renaming it would defeat the purpose of standardisation. Instead of unifying the language, it would create confusion among users who know what Markdown is but do not know “CommonMark” or vice versa.

And no, I do not think it fair or reasonable that whoever first coined a term gets to control its meaning forever. Especially when he just reused an existing dictionary word.

Basically, Gruber is asserting that because he came up with the concept, he gets to decide that no one can fix its flaws and clear up its ambiguities, and because the problems that stance causes to thousands of people do not affect him, we can all just kiss his self-righteous posterior.

Re: Compare AsciiDoc and Markdown

#118

Post by m-p-3 »

mikl wrote: post #117
blacktriangle wrote: post #115

Earlier quoted context omitted.

So then name it something else than Markdown? Gruber invented and published it, its fair that he gets to protect the name.

Renaming it would defeat the purpose of standardisation. Instead of unifying the language, it would create confusion among users who know what Markdown is but do not know “CommonMark” or vice versa. And no, I do not think it fair or reasonable that whoever first coined a term gets to control its meaning forever. Especially when he just reused an existing dictionary word. Basically, Gruber is asserting that because he…

Then let's stop referencing it as Markdown and let's all use the CommonMark name.

Re: Compare AsciiDoc and Markdown

#119

Post by mikl »

m-p-3 wrote: post #118
mikl wrote: post #117

Earlier quoted context omitted.

Renaming it would defeat the purpose of standardisation. Instead of unifying the language, it would create confusion among users who know what Markdown is but do not know “CommonMark” or vice versa. And no, I do not think it fair or reasonable that whoever first coined a term gets to control its meaning forever. Especially when he just reused an existing dictionary word. Basically, Gruber is asserting that because he…

Then let's stop referencing it as Markdown and let's all use the CommonMark name.

Ah yeah, try to educate millions of end-users about the new name, change the file extensions on 15 years worth of files, update reams of documentation, libraries and applications.

Does that sound even remotely feasible? I think not.

For better or worse, we’re stuck with the name, because trying to change it and failing would just create more compatibility problems and confusion.

Much like the eternal GIF pronunciation controversy or tabs vs. spaces, we’ll all just have to grin and bear it, because Gruber is not likely to change his mind.

Re: Compare AsciiDoc and Markdown

#120

Post by charles_f »

breuleux wrote: post #93
charles_f wrote: post #89

Earlier quoted context omitted.

My one comment: what I like about Markdown is that the "code" itself is readable, you don't have to effectively transform it to HTML, as is it almost looks like some text with a few characters here and there to emphasize things. Quaint's .q files look too much like source code to me, you wouldn't want to read them as is.

Could you be more specific as to what looks too much like source code? The most common difference between the two would be *multi word emphasis* vs _[multi word emphasis]. The former may be less conspicuous, but both read fine to me.

Sure. What I mean is that quaint files (e.g. [1] and [2]) look like simplified HTML ; you're defining functions, div hierarchy, formatting and such. I cannot comfortably read the .q, I have to read the rendered HTML. On the other hand, this [3] looks like a text file with ASCII formatting ; the fact that it compiles to HTML is almost incidental.

[1]: https://github.com/breuleux/blog/blob/master/content/about.q [2]: https://github.com/breuleux/quaint-doc/blob/master/content/i... [3]: https://raw.githubusercontent.com/breuleux/earl-grey/master/...

Post reply on HN