Hacker News Reader

Call it blasphemy but in my opinion the markdown is easier to read than the orgmode in your examples. Especially when you think away your syntax highlighting. Markdown is not just for short notation over html, it is also for readability of plain text. I'd argue it's better suited at that, especially to the untrained, than orgmode. I use markdown in my organization because even non-technical people can write and read it easily and without top much eyestrain (and we convert it to websites and pdf for official release).

I also disagree with the original post to the extent that it is correct but attacks issues that are not there in practice. Yes, there are multiple versions but this is not a major issue. Most people use github flavored anyway. There is an initiative to standardize markdown by the way [0]. The fact that it is not really taken up tells me there is no big issue with having multiple markdown flavors.

[0] http://commonmark.org/

There's a big difference between seeing an Org file in raw vs in an editor. This is how I see it: https://ox-hugo.netlify.com/images/ox-hugo-doc-source-viewin...

Also, I prefer not leaving empty blank lines in between. Factors like that can change one's perception of readability.

"It looks fine when you use the right viewing tools" is not a plus for a plaintext system

The plusses of plaintext systems are:

- free data (not locked by proprietary systems like Word) - ability to diff, search easily - ability to quickly refactor (biggest one for me) of not just content but markup too!

Now readability is subjective plus if you know what you are reading.

If you know Org markup, reading even raw Org will be easy. If you know Markdown, reading Markdown will be easy. If you don't know Org, you might think that the headings look like bullets. But that just because you don't know it not because if is less 'readable'.

I linked the raw Org earlier. Here is the Markdown conversion of the the same Org source: https://gitlab.com/kaushalmodi/kaushalmodi.gitlab.io/raw/mas...

To a Markdown-untrained eye, that wouldn't look too "readable".

Now of course, if you use a good editor that allows folding of headings, optional hiding of markup, coloring code blocks in the right syntax, etc, that definitely becomes more readable than raw. The same applies to Markdown.

It's basically -- Pick the right tool to make the experience more pleasant. But even if you use a wrong tool, plaintext content will allow you to get the job done. It's your choosing.

So as I mentioned earlier, "readability" is a perception, subjective to each individual. Based on their experience with plaintext, Org or Markdown "readability" can change. But the plusses of plaintext I mentioned in the very beginning stay unaffected by that.

The problem is that while I do know my setup, I can't trust that of my colleagues. You'd be surprised how many engineers even run without proper tooling. I.e. Are used to things like bare UltraEdit or Notepad++ for editing these kind of files. Especially the older generations (no offense). In addition, I have non-technical people who only use notepad to update the files.

Also, your markup without the blank lines and the fact that headings look like bullets to me make it harder to follow.

> your markup without the blank lines and

That's because I like that and only I am using that.

If it's a matter of team collaboration, certain ground rules can be set to resolve that.. like use blank lines after headings. You might be surprised but there's actually an Org mode setting in Emacs which can be configured to set how many blank lines to auto-insert after each heading -- I set that to zero.

> the fact that headings look like bullets to me make it harder to follow.

If you start using Org, it won't look like that. In fact, I use hyphens for list items in Markdown too as they work there too, so there is not too much context switching as I switch between Org and Markdown. I went through a lot of that as I was developing the ox-hugo package :)

Also in Org, lines starting with "# " are comments, which intuitively are comments in many languages. Markdown doesn't have comment syntax! I need to do stuff like below to fake a comment in Markdown:

    [//]: # "comment"

So the "headings look like bullets issue" will wear off once you start using Org, and then you wish Markdown also did the same :)

> Markdown doesn't have comment syntax!

Sure it does, . This is also what Emacs will automatically use if you add-file-local-variable in a Markdown file, so I don't know why you're using that weird format.

There's a stronger argument to made that org-mode doesn't really have comments. As far as I can tell syntax-ppss never gives me non-nil for them. Sure, a line like "# foo" appears in a comment face, but so does a line like "#+ASDF:" or "#+BEGIN_SRC" (but not a line like "#+TITLE:"). So whether something is a "comment" depends on its contents, which means it's syntax, never really a comment.

> Sure it does, . This is also what Emacs will automatically use if you add-file-local-variable in a Markdown file, so I don't know why you're using that weird format.

I was thinking of native comment syntax in Markdown, which is absent. But you are right, HTML comments, like anything else HTML work fine in Markdown. So you have a valid point.

> There's a stronger argument to made that org-mode doesn't really have comments. As far as I can tell syntax-ppss never gives me non-nil for them.

Hmm, I had never checked that. That's good to know. M-x comment-dwim works though. This might be good to report as Emacs bug.

> Sure, a line like "# foo" appears in a comment face,

That's a proper comment as per Org spec. Those lines are completely ignored by Org, for any parsing or for any exporting business.

> but so does a line like "#+ASDF:" or "#+BEGIN_SRC" (but not a line like "#+TITLE:").

Because those are not comments. It's not an official term but I think of those as pseudo-comments. The "#+.." lines while looking like comments have a special meaning to Org. The meaning of those can also be exporter backend dependent.

> So whether something is a "comment" depends on its contents, which means it's syntax, never really a comment.

Yes only for #+ comments.

`#+...` is called "affiliated keyword" in the spec[1]. Those are distinct from comments, which are required to have a whitespace character after the hash sign[2].

[1]: http://orgmode.org/worg/dev/org-syntax.html#Affiliated_keywo...

[2]: http://orgmode.org/worg/dev/org-syntax.html#Comments

> M-x comment-dwim works though.

This is because org overrides massive amounts of Emacs default functions - in this case, in org-setup-comments-handling. org-mode doesn't really use syntax tables normally. Similar problems occur with strings. They are known issues, and unlikely to be fixed.

The problem is you don't need to convince me. I could easily switch to org mode. It's the generic public that concerns me. You have to admit most people use stars as bullets. Even languages like wiki do. But also things like onenote and office things.

I'm not sure where this got off the track, but is anyone trying to convince the general public to use org? ox-hugo is an org package and org is centrally dependent on emacs. If you use emacs org, this is useful, if you don't it's probably not.

But if you do use emacs and org, there's absolutely no question that org is more readable than markdown. It's a bit like comparing Word to plaintext, they are just not the same tool.

EDIT: I guess the article could be interpreted as convincing you to switch to org so that's probably what you mean, but I sort of read it as "if you use emacs, org is better than markdown", which I can't really argue with. But if emacs is a non-starter for some people, I find pandoc is very useful for moving documents back and forth.

The "older generations" wrote the tools we are talking about.

It confuses me to understand if this is advocating org-mode or "an org-mode aiding tool".

But think again, if it's a good plaintext markup language, why would we concern about an editor anyway?

TBH the time it's being useful is when I am writing in _any_ plaintext editor. Not a great example but if I'm already used to pressing Ctrl + B for the past twenty years, why would Shift + _ suddenly make things better?

> if it's a good plaintext markup language, why would we concern about an editor anyway?

I work with a colleague who edits Org mode files in Vim just fine. But if you use Emacs to edit the same file, you get the benefits of subtree folding, syntax highlighting, etc.

You can get the same in Vim too, but someone has to develop a plugin for that.

So talking about my colleague editing Org mode in Vim, once he is done editing, he runs a Makefile that runs emacs in batch mode to run the Org exporter.

> TBH the time it's being useful is when I am writing in _any_ plaintext editor.

You still can, as I mentioned above.

The benefit of plain text is that it can be easily edited in any editor. Now emacs just adds features related to viewing (folding, syntax highlighting) and navigating on top of that. Given time and enough interest, any editor can support those features for Org mode files.

It's worth noting that Hugo now has native org mode support https://discourse.gohugo.io/t/org-mode-content-support-merge...

Of course I am aware of that :)

I did my "market study" before I started investing time for this project. I have a page on ox-hugo Documentation site (the first link in my original comment) that talks in detail why I needed to have a ox-hugo: https://ox-hugo.netlify.com/doc/why-ox-hugo/

I think org-mode is good. But I think that it and markdown could have better syntax for links. Like a link doesn't have to be wrapped in an opener or closer, since any spaces can be escaped. So you could simply do:

~A new search engine@https://google.com

I think considering the status of @ in the rfc this can be parsed. If a link has spaces just replace them with + or %20

A main goal of Markdown is to be easy for anyone to use. Having to substitute characters in a URL string might be fairly trivial for you or me, but certainly not for everybody.

It's a trade off definitely. The way I think of it is, how often would you have to sub? Rarely. Since most uris do not have spaces, and even putting a URL in an address bar will usually sub it.

On the plus side, having a simpler syntax for URLs I feel is more readable which is great for ease of use. I think ~ looks like a link, and @ makes sense semantically.

But to be sure I think the legacy syntax could remain as a fallback / alternative. New syntax is something that could be tried in a flavor.

For people who don't find writing in native emacs a bonus, such posts are very straight forward to write in jupyther notebook. It even one up most other editors code highlight by rendering markdowns blocks inline.

Cool, I've been looking for exactly this tool.

Thank you. Please try it out and open as many issues as you can. I'd like "ox-hugo" to just work for others as it has for me.