Org-Mode Is One of the Most Reasonable Markup Languages to Use for Text | Hacker News Reader

Org-Mode Is One of the Most Reasonable Markup Languages to Use for Text

karl-voit.at

556 pointspmoriarty241 comments

Looks pretty nice. One nit:

    : Simple pre-formatted text such as for source code.
    : This also respects the line breaks. *bold* is not bold here.

This makes it annoying to cut/paste code in and out of the markup text. It's better to use a block syntax for that, like:

    ```
    Simple pre-formatted text such as for source code.
    This also respects the line breaks. *bold* is not bold here.
    ```

> This makes it annoying to cut/paste code in and out of the markup text.

Well, not that annoying because you're inside Emacs and operating on rectangles of text is a doddle. But the preferred syntax is to enclose the source code in #+BEGIN_SRC/#+END_SRC blocks anyway.

Using this method also enables neat features, such as activating the appropriate major mode for each block of text and doing literate programming.

> because you're inside Emacs

No, I won't be. The article also stated:

> Please do note that this is not about Emacs. This is about Org-mode syntax and its advantages even when used outside of Emacs.

Sorry, but a "reasonable" markup language in my book would be one I would be comfortably using anywhere, meaning typing in manually (which I do a lot with markdown). #+BEGIN_SRC/#+END_SRC is too verbose and ':' as a line prefix impractical.

This won't see any wide-spread adoption outside of the Emacs world, markdown's adoption is widespread and is here to stay I'm afraid, even though it has tons of pitfalls and different styles. For pretty much everything, it's "good enough", and some things make a lot more sense if you're actually typing the text.

Markdown does no better on this particular front; each line of preformatted text must be prefixed with four spaces which is EXCEEDINGLY impractical.

Block select, tab. That's it, since in every editor I use, I use space indents for markdown.

If using Evil mode or vim, it's just a few keystrokes to remove that. (ctrl-v to block select)

Or <s TAB (or <q TAB) will create a block.

You can use `C-c '` to edit the block in a new buffer without colons or indentation at the start.

As other mentioned, #+BEGIN_SRC / #+END_SRC (Emacs will expand "<s TAB" into that for you).

There are also #+BEGIN_QUOTE, #+BEGIN_EXAMPLE, #+BEGIN_EXPORT and some others. They all represent blocks of special text, and have special meaning in Org Mode and/or in exports to other formats.

For instance, a source block declared through "#+BEGIN_SRC language" can have syntax highlighting enabled using appropriate language mode in Emacs, can be easily edited (C-c ') in that mode, and can be also set to automatically evaluate and print results in the document (kind of like Jupyer Notebooks, except in Emacs, but more advanced, and also supports full-blown literate programming use).

As somebody who writes a poetry blog (from org-mode), I've learned the love #+BEGIN_VERSE, which respects text decoration markup but otherwise leaves formatting intact.

For an emacs user inserting "a column" of colon-space in front of some pasted text is pretty easy to do. But then even emacs users are often forced to type text outside of emacs.

Using backquotes (as required in bitbucket) is uncomfortable with my non-English keyboard. I have to type 6 backquotes instead of 3 because backquote is a deadkey

Emacs has rectangular editing so thats no big deal if one's using org mode in emacs.

So the argument that it is easy to write in any editor is not completely true then?

Yes, kind of. The true advantage of Org-Mode is the extensibility, which comes from it being implemented in Emacs Lisp and living in Emacs. That's how people have been able to bolt on so many useful things on it like Babel (not the JS thing) and the export mechanism, and how you can have many types of useful links both inter- and infratextual. It's so easy to link somewhere in the document, in the file system, in your mail boxes, and to some piece of code etc. Editing functionalities help, but Markdown too has similar stuff (spaces before code, > before quotes, etc.). The actual benefit of Org mode in emacs is that I can really easily program it to do what I want. I use the same tool to digitise and store my prose; create PDF documents with citations and whatnot; store all my personal and lecture notes; keep, interact with and browse my agenda; keep executable notes from my shell sessions with links to documentation and screenshots etc (a la IPython); and publish my website; and all these documents are easily hyperlinkable, and anywhere in them I can have to-do notes that I can easily have pop up in my agenda, and then export to ICS or CalDav to access them from my mobile phone (there are MobileOrg and Orgzly for viewing documents on mobile, I use the latter). I don't know how you can do such things in another environment than Emacs, while both providing the same interactiveness, the same extensibility, the same customisability, and remaining resource-efficient on the computer and using only a single programming and configuration language.

> The true advantage of Org-Mode is the extensibility, which comes from it being implemented in Emacs Lisp and living in Emacs.

I feel this cannot be overstated. I am finally moving from a 2009 Nokia N900 to Android only because I know I can run Emacs+org-mode in Termux on it, and I can get a hardware keyboard.

Yeah, that's my problem with org mode: if you're not on emacs, you're a second class citizen. It's a natural outgrowth of the fact that it started as just a tool for emacs users.

> if you're not on emacs, you're a second class citizen

Emacs is central to the org-mode experience because all of the goodness is implemented in emacs lisp. Most everything I do with it is an extension of that (custom capture templates, todo lists and agendas, etc.) A standalone tool just wouldn't cut it for me. If I need to share something I've worked on in org-mode, I'll export or use pandoc to get it into something useful for a non-emacs user.

EDIT: I also don't find org-mode difficult to read outside of org-mode, but I'm also pretty familiar with it. It does frustrate me when I open up notepad++ or something similar to check an org-mode files and my tables don't format automatically.

Or {{{ }}} as used by Creole. Unlike Org-mode, which despite the OP's claims is not at all standardized, Creole is an actually standardized [1] (but probably still under-specified) lightweight markup language. As shown on the Wikipedia page [2] it has pretty much all the other mentioned advantages.

Another important advantage of using block syntax is that it offers a natural uniform extension mechanism, potentially even with auto-completion for improved discoverability. For example Trac uses this for source code highlighting and plugins.[3]

[1] http://www.wikicreole.org/wiki/Creole1.0 [2] https://en.wikipedia.org/wiki/Creole_(markup) [3] https://i.imgur.com/zbkU670.gif

> Ignore // for italics processing if immediately following http: or ftp:

That kind of special casing is pretty much a deal-breaker. Other schemes (anyone ever heard of https?) will need that same deal.

> This makes it annoying to cut/paste code in and out of the markup text.

Open it in it's own pane with C-c ' and you can cut and paste to your heart's content.

> Any tool that interprets Org-mode accepts this simple and easy to remember syntax.

Sorry but this just isn't true. org-mode doesn't have the standardization problems Markdown does only because it's not as popular. As far as I know org-mode also doesn't have a standard, just an official implementation. And all the unofficial implementations suffer from bugs where they do something a little differently (https://github.com/bjonnh/PyOrgMode/issues/39 , https://github.com/hsitz/VimOrganizer/issues/78 , plenty of others in every org-mode tool that doesn't just call Emacs).

This isn't to malign any of the authors of these tools, but the reality is without an actual specification the problems are exactly the same as Markdown's - everyone is chasing subtle implementation details, not a clear goal.

IMO, org-mode only makes sense in the context of editing within Emacs. The (enormous) value isn't in the file format, which doesn't really offer anything over GFM, but in the editing tool itself - which is difficult enough to realize inside of Emacs, let alone in any other editor - and its integration with other Emacs tools.

I find much of the criticism against ("the") Markdown opinion-based. For instance, I hardly can remember whether it is `[http://example.com](foo)` or `(http://example.com)[foo]` in Markdown but I would also confuse `[[http://example.com][foo]]` with `[foo][http://example.com]]`.

In the same spirit, one may like or hate `*` for indicating headings (the choice is really unnatural for me, always thinking of a list).

The way I remember [] before () is that [] is "basic" and square and () is "refined" and curvy. Seems silly but it helps me.

I remember “brackets come before parentheses” alphabetically ;)

These are both helpful mnemonic tricks. I always forget links' syntax.

More generally in this post I find Markdown has a pretty short learning curve, is highly readable and logical (EG. I like the number of `#` for level of headings). My biggest issue with Markdown is the different interpretations and how they're represented. Eg. Github vs. someplace else vs. Markdown-viewer apps. Org in comparison looks more concise, but less readable, IMO.

"squared circle" = []()

https://en.wikipedia.org/wiki/Squaring_the_circle

i can't remember who i heard it from first, but "squaring the circle" is the phrase that (finally!) helped me remember the order after years of having to look it up every single time i needed it.

i still have to look up the format for images every time.

I always sort of read it to myself. I use parens within normal writing as an aside (for example, this one), so I put the part that you read within the brackets and the reference in the parens.

In plaintext you'd have a claim (and parens directing you to see the citation at citation.com).

In hypertext you'd have a [claim](and a link to citation.com).

The way to remember that is that the link is important.

For example, [[www.example.com]] makes sense.. it will render as www.example.com that hyperlinks to that link. But [[link description]] is useless by itself.

So.. put the more important thing first, the link:

    [[www.example.com]]

Now, if you also have a description text for that link, put that afterwards..

    [[www.example.com][link description]]

Hope that helps.

Often the link description is the most important thing, and may make sense without the link, so I'm not sure how well that would work.

To me putting the link first is extremely counter-intuitive, as if writing plain text I'd also be more likely to write out a description of what I'm referencing first, and then enclosing the link in parentheses.

Thankfully with Markdown that makes it easier to remember - the URL part is as it always was, and I just need to mark which part of the text makes up the description.

In html the link comes first <a href="link">Link Text</a>. So I would bet that most people are more comfortable with the link coming first.

I'd argue that if you are writing text, you'll put the description first and then look up the link. Because the description is often part of the sentence, and the link is not.

In fact you may write the entire thing first then look for whatever can or should be hyperlinked.

Most people wouldn't be able to explain to you what a HTML tag is, much less write one.

And the entire point of Markdown is to get something that is closer to how we write plain text.

I'm more comfortable with the text coming first, followed by the link. The rails `link_to` helper is:

> link_to "Text", "http://example.com"

And Markdown:

> [Text](http://example.com)

It's pretty easy to remember the order after a while.

Clearly the link is more important than the link description. There is a really surprisingly good document [here] that explains why in detail :P

You never should use "here" for links. It's bad semantics for hyperlinks, and there could be tens of thousands of links with the title "here." Compare:

> [The W3C recommends not using "here" or "click here" for links.](https://www.w3.org/QA/Tips/noClickHere)

According to the original vision of hypermedia, the text should be able to stand on its own and the hyperlinks are added on top of it. This keeps the link text semantic by itself without relying on the hyperlink.

Short of explicitly labeling each part (which would not be in spirit of 'lightweight markup'), it's hard to imagine any link/description markup that is completely foolproof. The advantage over markdown here is that you are really only likely to get one part of the links wrong: the order. In markdown, you might also get them out of order but you may get the brackets wrong too. Then, having realized something is wrong, fixing it way more complicated. With Org-Mode, you notice your link isn't working right so you swap the order and you're done.

I struggled with it, until I learned about "reference style" links in the original Markdown spec:

this is a link [1]

[1]: <link>

would display 1 and direct you to <link>. Then inline links are just reference links but you have the location in parenthesis after the link body, as an aside.

The reference style is my mnemonic to the order as well as where the parentheses are for non-reference links: since the reference definition uses []: then the reference uses [] too, and since the reference comes naturally after the text, then a non-ref link has the URL in not-[], hence (), and after the text too.

IOW I just think about "inlining" the reference, which would have otherwise used [] everywhere. Feels much more regular that way around.

To me, markdown and org-mode look completely equivalent. Surely there are small differences, which have to be learnt. Either way you have to remember some small details.

In org you don't need to remember. You just `C-c C-l` and it interactively asks for a link. You can type it or paste the link from your clipboard. _Then_ it asks you for an optional description.

The same command works if you want to edit a link under the cursor.

Also, most people have `C-c l` bound to a function that “captures” the link from wherever you are in Emacs (e.g. a newsfeed, a document, an email, a folder) so you can easily reference those places from within Org.

I think we should either compare these languages in a plain text editing context, or when used with editors with support for the syntax. Anything else seems like an unfair comparison to me.

Because editors with MD support tend to have shortcuts for inserting a link or image too, so this isn't really an argument in favour of either syntax.

I agree with you. My intention was to perhaps highlight one of the ways that using Emacs can help someone be productive using markup (but as you pointed this is probably true of other editors with strong support for the language) and maybe help someone discover an important feature of the editor that they have missed.

"Most people" :)

Fraction of people who have Emacs installed. Fraction of people who use Emacs for things other than programming. Fraction of those who use org-mode.

Well, "most people" in the context of my comment was exactly that small fraction. You really thought that I was talking about the entire world?

As an Emacs user I know most of humanity is far from ignumitation. (And also have bad sense of humor)

As mostly an org user, I still find that part of the markdown syntax to be more intuitive: parentheses are commonly used to clarify or expand on something, and links are often inserted with the same purpose, so a link goes into parentheses. E.g., "foo (you can find it there)".

Shameless plug: https://ox-hugo.netlify.com

I just announced the ox-hugo package. I love the blogging framework of Hugo, but disliked that I needed to manually take care of the post front matter and also noticed the shortcomings of writing in just Markdown. I also missed the tree-based text organization of Org mode. So this package was born.

Writing posts in Org mode gives you all the Org markup power (that's already more than Markdown), plus a lot more! like Org Babel, property inheritance, etc.

An example: I wrote this post ( https://scripter.co/notes/string-functions-nim-vs-python/ ) that's heavy with code blocks and results of evaluating those code blocks. It would be super-painful in Markdown to paste all the code blocks and also their results. In the Org source: https://gitlab.com/kaushalmodi/kaushalmodi.gitlab.io/raw/mas..., each of the #+RESULTS blocks in that Org source are auto generated using the Org Babel feature.

I elaborate more on why I use ox-hugo, or why I use Org for blogging in native Emacs environment here: https://ox-hugo.netlify.com/doc/why-ox-hugo/

Even if one is not using Emacs as their editor, as the OP mentions, the Org markup is simple enough that anyone can use their favorite editor to write in Org. To add to that, using a little Makefile, they can run Emacs in batch mode to take advantage of true Org mode features like Org Babel, etc.

For instance, one can clone the ox-hugo repo, https://github.com/kaushalmodi/ox-hugo/, and just run "make test" or "make doc" to let ox-hugo do its thing, without having anyone to know what to do after opening Emacs, what command to run, etc.

"make doc" will generate all the Markdown content needed for the entire documentation website that I linked in the very beginning of this comment, all from a single Org file.. You cannot do that in Markdown.

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.

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 :)

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.

> 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.

> 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.

`#+...` 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

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

"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.

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.

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.

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.

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/

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.

I love org-mode, but have to write GH flavoured markdown for work. It really is a second class citizen in comparison.

Org tables are sublime. I quite often fire up orgtbl-mode just to create tables easily in other text documents.

Writing code blocks, in a language's major mode, is amazing. Just C-c ' and you're away, complete with your emacs tool chain, which for me means I get Python syntax highlighting, autocomplete and a PEP-8 checker. Then you can use babel to present your output.

Export to html, pdf, odf works brilliantly, and I can specify a CSS sheet to style it however I want.

And lastly there's https://github.com/yjwen/org-reveal which let's me make slide decks effortlessly.

Great examples of power features. When we started using markdown for work, I was surprised that tables were kind of a pain and pandoc's recommendation was to use Emacs and org-table.

I'm a bit late to the thread, but I second this. I have most of my life workflow in org now, and while the learning curve was not the easiest it has been worth it. I particularly enjoy the export options, like latex to PDF, and combined with pandoc, I can go from org to just about any format.

I'm currently trying to learn to use the time tracking functions better.

Emacs really is an OS. Linux is just my (current) kernel.

I use markdown for academic writing, and take huge advantage of related markdown extensions provided by pandoc. For example:

This is normal text^[And this is a footnote, which will be rendered as such when converting to, say, LaTeX]

I can also add citations [@likethisone, p. 12]. Pandoc will look up and format that bibtex reference for me.

Is there anything like that for Org-Mode?

org-mode does indeed support footnotes[fn:1], but I was recently saddened to find that Github doesn't render them (it does render more basic org-mode features, though).

org-ref[fn:2] has extensive support for for citations and is explicitly designed for scientific papers and output to LaTeX.

[fn:1] Check out http://orgmode.org/manual/Footnotes.html

[fn:2] Check out https://github.com/jkitchin/org-ref/blob/master/org-ref.org

> org-mode does indeed support footnotes[fn:1], but I was recently saddened to find that Github doesn't render them (it does render more basic org-mode features, though).

GitHub uses this org-ruby project[1] to render Org files. If someone loves Org and knows Ruby too (I don't), please open PR's on that repo to improve Org parsing.

[1]: https://github.com/wallyqs/org-ruby

Slightly off topic but I have to ask: would you be willing to share your markdown workflow for academic writing? I am very interested in graduating from latex :)

I would second this, having written a lot of documentation recently (markdown + template + pandoc -> pdf) I am very interested in improving this workflow.

Me too. Particularly I am interested in knowing if the setup auto-suggests items from the bibfile when typing [@

That's a big one for me that I've only gotten to work in online latex tools.

There are plugins to do this in Vim, Atom and I'm sure other editors as well. See one academic's description of how to tie it all together here: http://wcm1.web.rice.edu/plain-text-citations.html

This is somehwat geared toward my specific preferences as a social scientist, but my cookiecutter template contains pretty much everything you need for academic writing using pandoc: https://bitbucket.org/jboy1/cookiecutter-pandoc-paper

You can also consult Kieran Healy's guide here: http://plain-text.co (again, this targets social scientists)

Yeah, bibliography works with org-mode. You can also do cross references in org-mode, which last I checked were a showstopper for me with Markdown.

I've tried doing academic writing in both org-mode and markdown. Org-mode ended up being the only one that did everything I needed.

The article doesn't really seem show any compelling use case of org mode being better than Markdown other than personal preference. Is there something feature wise I'm missing?

I’d say the strongest point vs markdown is which version of markdown. Markdown is hardly a standard.

Is org-mode a standard, beyond having only one implementation? You could just pick one markdown implementation.

Other than emacs, some things have very partial orgmode implementations, but they tend to be very partial, much more different to markdown implementations.

All I could think of when he said that was this: https://xkcd.com/927/

I used org-mode for note taking and writing for about 9 months.

I liked it, but there were some things that really irritated me

- Exporting to other formats is not as clean cut as it first seems, especially if you use org-mode features like tags, LOG drawers etc. I always had to spend time fixing things up after the export which got annoying

- It's not very easy to move from org-mode to <insert other note taking tool here>

- Accessing your notes on other devices is a hit and miss affair, especially on Android devices

I'd say if you're interested in using it for writing blog posts etc then you'll probably experience none of these troubles, but I'd just proceed with caution first

I've dealt with those shortcomings in the following ways:

- exporting: some lisp magic can help you here, such as automatically assigning custom properties to drawers. This isn't everyone's cup of tea, but it has helped quite a bit for me.

- pandoc supports org, which makes it trivial for my usecase. It may not be for everyone, but pandoc is very powerful.

- Have to agree with you here. I like orgzly, but it has its shortcomings. It is nice to be able to use a plaintext editor in a pinch, however. I don't have that option with most other tools.

I love orgmode, but what's the advantage over asciidoc? asciidoc looks cleaner to me

the other small disadvantage is that text isn't really bound to headers. So headers and text just kinda float around meaninglessly. So you can't have:

* Header topic1

introductory text

* * Subheader

some descriptive text related to the subheader

more text to wrap up topic1

I'm a big fan of asciidoc - I started using it for all my technical documentation a few years ago and haven't looked back. It gets the balance between simplicity and features just right.

> what's the advantage over asciidoc?

Exactly what is states in the article.

Asciidoc has 3 different types of headings (prefix, pre-postfix and underlined).

    http://example.com[Text]

The form is simple but for complex URLs, the [Text] might look like being part of the URL itself. Not beautiful but at least something I could live with.

Additionally asciidoc uses ===== for underlining headings and for delineating code blocks.

the other small disadvantage is that text isn't really bound to headers

Surely this is true of all markup languages. How you would represent this visually in a document?

> Surely this is true of all markup languages. How you would represent this visually in a document?

An extra newline between the end of the inner part and the return to the outer part, which is what I do naturally. This can get unwieldy for breaking out of more than one level, but that's rare enough you can handle that with an alternative syntax like "--" alone to break out of two levels, "---" to break out of 3, etc.

Another possibility would be picking up ASCII SI/SO again. (Emacs already makes extensive use of FF.)

"Surely this is true of all markup languages. How you would represent this visually in a document?"

Not to be snarky, but the ML in XML and HTML stands for markup language..

I'd like my markup to be easy to read and also to map to a tree hierarchy. This seems essential for parsing and anything related to literate programming and reusing "blocks"

Like when I drop in a org mode clock (for logging time in my work logbook), without a tree hierarchy I have no means of binding the time to my description of the work I did. I mean... I see in visually, but its not programmatically linked as an attribute of that text block.

You can kinda get around with pepperin headers everywhere, but it's not as flexible

On Windows, not having to install DocBook tools.

Org-mode is awesome.

- supported in GitHub: README.org

- ipython integration allows full code execution to generate inline plots by executing the code in the document.

- many other features too numerous to mention; it’s the truly ancient granddaddy of markup, developed over decades.

Surprisingly org-mode is nowhere near as old as emacs. It was "born" in 2003

- ipython integration allows full code execution to generate inline plots by executing the code in the document.

Of course, this is not restricted to iPython/Jupyter. Babel allows you to execute code in many languages inline, without running a full Jupyter instance/kernel:

http://orgmode.org/worg/org-contrib/babel/

You can also generate inline plots with Babel. Let the code snippet generate an image, return the file name from the block, and set the result type to file.

I've been using Org-mode to make notes on math and computing. The best part is how easy it is to embed LaTeX math equations. I can simply do this:

  * Heading

  Euler's identity: \(e^{i\pi} + 1 = 0\)

Then <C-c><C-e>lp to export to PDF and I have a neatly formatted document with properly rendered math. This is a lot easier than taking notes in LaTeX, and I can use any LaTeX packages. The ability to embed and execute source code makes it very easy for literate programming. Exporting to HTML or ODT is also possible.

No one has mentioned metadata. Yes, Org Mode is a kitchen sink, for better or worse, but at least I can make annotations, even some structured data. Markdown doesn't even have comments.

I won't criticize Markdown (or anything) for failing to achieve what it doesn't attempt, but as a programmer I consider any format with fixed semantics to be, as Bret Victor might say, "dead fish." I know XML has a bad rap (for good reasons), but at least they were trying to be extensible!

As far as I understand it, Markdown is a superset of HTML (with some caveats). So Markdown does have comments, they're the same as HTML comments.

From https://daringfireball.net/projects/markdown/syntax

> For any markup that is not covered by Markdown’s syntax, you simply use HTML itself. There’s no need to preface it or delimit it to indicate that you’re switching from Markdown to HTML; you just use the tags.

> The only restrictions are that block-level HTML elements — e.g. <div>, <table>, <pre>, <p>, etc. — must be separated from surrounding content by blank lines, and the start and end tags of the block should not be indented with tabs or spaces. Markdown is smart enough not to add extra (unwanted) <p> tags around HTML block-level tags.

No, it's still an HTML comment - it will be present in the output generated from Markdown. If it was Markdown comment, it wouldn't show up in the output.

If that is a feature or a bug depends on perspective and if a Markdown renderer strips HTML comments or not is an option for many of them.

(That said, I do miss the reStructuredText comments sometimes in Markdown, but partly because the syntax was so simple.)

As a programmer, I consider a format that is deeply tied to one particular editor as "don't touch it with a 10 foot pole". Org-mode without emacs isn't particularly attractive (I prefer markdown or asciidoc when it comes to syntax; tooling and popularity are limited). And I have no plan of learning emacs or elisp(!). In a way, org-mode is the .doc of markup languages.

+ Easy to learn

+ Easy to read

+ Good support in major text editors

• Started in the emacs world

• Been around since 2003

- Would put a strikethrough all the advantages above because they use the + symbol.

> Would put a strikethrough all the advantages above because they use the + symbol.

No, it wouldn't. `+` is a valid list bullet in Org-mode. For strikethrough, the plus-signs must be attached to the start and end of the words (`+an example+`).

Thank you for clarifying! So it's just my phone number that will be striken-through.

+88673630588+63377

No, it wouldn't. The end plus-sign must be at the end of the word.

Why is strikethrough not a minus sign?

i.e. -strikethough-

I assume whoever made the decision figured that minus-sign is more commonly used for other purposes in text (although usually one should be using an en/em dash (which would be `--`/`---` in Org-mode) instead), so it would be harder to read (especially in text-mode where you don't see the strikethrough).

> usually one should be using an en/em dash (which would be `--`/`---` in Org-mode

This is something I've never liked about org-mode. Markdown was designed to be authored in existing tools, so its conversion of ASCII to Unicode quotes makes some sense. But Org is defined by its Emacs implementation, and Emacs has always had electrified punctuation support. There's no reason to export -- as –, and therefore need to deal with escapes, etc., when you can make -- insert – and export literally.

The fancier the editor, the fewer special syntaxes you should need in the format.

As everything else, that can be disabled too. Org mode/Emacs is immensely configurable. See http://orgmode.org/manual/Special-symbols.html and `org-export-with-special-strings` in http://orgmode.org/manual/Export-settings.html#Export-settin...

Further balkanization of the export behavior isn't an advantage! Comparisons to the minor incompatibilities of Markdown parsers is laughable when the solution to concerns about the format is "customize your local Emacs."

> Further balkanization of the export behavior isn't an advantage!

I'm not sure I understand that. You need to customize the export behavior because everyone doesn't prefer the exact same thing. While you prefer not to auto-convert to en/em-dashes, I prefer that. So having options (what you refer to as balkanization) is good.

> Comparisons to the minor incompatibilities of Markdown parsers is laughable

Didn't follow that. What incompatibility is this in reference to? Which parser? Of which flavor of Markdown?

> when the solution to concerns about the format is "customize your local Emacs."

How else would every user get their export behavior unless customizability is added? Taking the same example as yours, I am glad that "--" does the job of "–" or "–".

I know of one Markdown parser (Blackfriday) that adds a similar en-dash/em-dash conversation like Org exporter (and is enabled by default in Hugo). So the customization is needed by a sizeable number of people.

In the end, it's alright if you don't prefer Org mode or like the option to have options. I presented the ox-hugo package for folks who like blogging using Hugo, but don't want the leave the comforts of Org mode. I am not enforcing Org mode on anyone.

Everything I'm writing is in the context of the original article - "Org-Mode Is One of the Most Reasonable Markup Language to Use for Text" - which I think is totally false.

Org-mode is an amazing tool and I use that tool every day. But to the extent there's an org format, it's not very good, and it's less interoperable than Markdown (the interoperability problems of Markdown are cited by the author as a major reason to avoid it).

I didn't write anything about ox-hugo or Hugo, and I don't know why you brought up either.

I'm surprised nobody mentioned MarkDeep as an extension to MarkDown[0]. It features a lot of convenient extras, and Morgan McGuire (who created it) has slowly been improving it over the years.

https://casual-effects.com/markdeep/

shameless plug: https://github.com/theodorewiles/org-mind-map

cool! I'll have to try this out :)

I'm sold. Is it a (near or full) replacement for markdown?

I can't think of a single thing it can't do that markdown can do, but I can think of several things it does that markdown doesn't do.

Main problem (as I note in another message) is lack of feature parity in non-Emacs implementations and lack of quality html renderers outside of Emacs.

> I can't think of a single thing it can't do that markdown can do

Be human-readable, for starters.

That's subjective. I know org-mode and prefer it. The people espousing the intrinsic comparative readability of Markdown all appear to be deeply steeped in that world.

For me the org-mode syntax is more logical than Markdown—and I can have cross references.

You know org mode and prefer it, fair enough. To someone unfamiliar with both syntaxes, Markdown is much easier to grasp; because it's simpler it's just more readable.

Is that true because you're privy to the results of that experiment? Or is it true because you're most comfortable with Markdown and are starting from the unshakable belief that Markdown is intrinsically easier?

To be honest, Markdown feels simpler because it's quite less featured than Org.

If you put a Markdown document and an Org document implementing only what Markdown can, there's no readability difference between the two as I know both markup style fairly well.

Org Mode has a lot more functionality than Markdown. A document that only uses features present in Markdown seems to me just as readable in either format.

Which markdown? :-P

Some markdowns have some nice features:

- Fenced code blocks, which I would prefer to prefixing with colons (update: oh I guess org-mode has an equivalent! good)

- Footnote support

- Definition list support (<dl><dt></dt><dd></dd></dl>)

Additionally, it should be noted that Markdown allows usage of any HTML you want and it will be passed through. In practice this is often sanitized or escaped, but not always. On GitHub, for example, you are perfectly free to use <sup>, <detail><summary>, and so on.

Update Nice, Org-Mode does all that? Then that is a strong advantage over Markdown, where you never know which parts of which flavor will work on what site. (Heck, we can’t even get GitHub and StackOverflow to treat code blocks similarly.)

Org mode handles footnotes:

    some text [fn:1]

    [fn:1] this is where the footnote text goes

The one thing that I find weird is that if you convert to HTML using pandoc, those appear after an <hr>, but in the org mode itself, they'll appear as children of the previous sub-heading.

org-mode has all the features you mentioned. Following gives you fenced code blocks:

  #+begin_src c
  printf("%d", 1);
  #+end_src

it has both named and unnamed footnotes [1]. You can use '::' in a list item to create a description list, like so:

  + coffee :: a dark, bitter, stimulating beverage
  + tea :: a beverage with effects similar to but milder than coffee
  + beer :: an alcoholic drink made from grains

[1]: http://orgmode.org/manual/Footnotes.html

```...``` is about ten times easier to write and twice as readable as #+begin_tok ... #+end_tok.

It does look easier, but in practice one edits org-mode docs in Emacs so typing the three keystrokes s<[Tab] at the beginning of a line produces:

    #+BEGIN_SRC 

    #+END_SRC

The cursor is left at the end of the first line where one presumably types the word python or c or shell or whatever language you'd like the code block to be treated as.

Once editing the code block, typing C-' takes you to a dedicated editing pane that runs in an emacs major mode most appropriate for the language being edited, with full Emacs programming language support. It's really painless, other than learning Emacs first, (LOL, but honestly really worth it).

Easier to write, yes, but only outside of emacs (and anything with good snippet support). Within emacs, <s TAB expands to

  #+BEGIN_SRC |
  
  #+END_SRC

with the cursor placed to specify a language.

As for readability, I don't think it's clear at all that ```...``` beats

  #+BEGIN_SRC perl
  ...
  #+END_SRC

* * *

As it turns out, I hadn't refreshed the page for hours, and someone else said pretty much the same five hours before.

I'm mostly sold. The only downside is that the preformatted text blocks have each line start with a ':'. That makes it terrible for naive copy/paste from the source document...

But other than that, it really does look great.

In Emacs, <s + <TAB> at the beginning of a line starts a source block. The delimiters are quite distracting though. This is an issue I have with markup languages in general, either you use markup very sparingly or the document easily becomes unreadable.

And you can customize it too! In the past I have set up <r to create an R source block with some common code block parameters for R.

You can also format source code like this:

    #+BEGIN_SRC bash
    $ echo Hello, World!
    #+END_SRC

That will also give you syntax highlighting, and allow you to edit it as a bash script (in Emacs, at least).

I don't remember it off the top of my head, but there's also a similar syntax to include a file directly, instead of duplicating it in the org file.

#+INCLUDE

I love the concept of using lightweight markup text but a lot of the comments in the article also apply to Markdown. Personally I've switched to using Markdown for everything possible and have started using Typora as my rich text editor as it provides the first fluid WYSIWYG markdown interface I have seen with easy export to PDF / word / HTML.

WUSIWUG...WYSIWYG?

Yes!

http://acronyms.thefreedictionary.com/WUSIWUG

I tried to like Org-mode, but one major complaint I have with Org-Mode syntax is its inability to effectively handle text in a language without spaces; some format syntax and link can't be segmented in languages like Japanese.

I guess this is also said to be true for other format like markdown, but at least format like HTML doesn't have that problem...

And yet RTL languages ...

What about them? Does org mode handle them better/worse than other formats?

Could you provide an example document that exhibits the issue, and a more detailed description of what goes wrong? Say, to one of the email addresses in my profile. Thanks in advance!

Pretty simple things;

  テスト*テスト*テスト
  テスト_テスト_テスト
  テスト[[http://orgmode.org/][テスト]]テスト

Back when I actually have been using org-mode extensively (loved ID based document linking, Calendar file export, etc.) just I couldn't use it for anything that involves Japanese text which was 1/3 of things I had to deal with. I've actually tried suggesting on a developer's list for possibility of "negative" space where it can denote "space, but not quite space" which wasn't received well..

Yeah, that's a somewhat tricky problem, I think - the regexes depend on surrounding whitespace and are pretty hairy in general, as I recall. Something might be done with surrounding word boundaries instead, but I'm not sure how Emacs regexes handle those, and also unsure how the semantic applies in Japanese text - as I'm very unfamiliar with the language, I haven't yet found a chance to experiment. As I find the time, I'll see what I can do with these examples - thanks for providing them!

> `Text <http://example.com/>`_

> Holy moly. This is some weird stuff. First, you have to grave accents ` and not apostrophes '.

Because grave accents are rarely used on their own, and they were thus picked as rst's "meta-character" for roles (inline extensions). Apostrophes would be significantly more problematic.

> Then what about the underscore character at the end?

The underscore is actually how links are marked. The "core" form of external links is this:

    Text_

and at the bottom of the document would be

    .. _Text: http://example.com/

that way any instance of "Text" can be hyperlinked at little expense. Multi-word labels are simply wrapped in backticks:

    `This is text`_

    .. _This is text: <link here>

The inline form is provided as "a convenience at the expense of readability" using the generic role syntax:

    :role:`label <id>`

where for hyperlinks `:role:` becomes an underscore postfix.

> This is as complicated as you can define a simple URL. I'd even prefer the hard to type HTML version of linking. A disaster for something which has "lightweight" in its class name.

rST was designed as a lightweight markup for documents, hence its support for footnotes, citations, substitutions, document fields and built-in extensions hooks (roles and directives). The "inline external hyperlink" use case wasn't much of a focus.

As a criticism of rST as a lightweight markup, title denotation is probably a much better target, they look OK in plain text but are a chore to write and maintain, even with editor help.

> Because grave accents are rarely used on their own, and they were thus picked as rst's "meta-character" for roles (inline extensions). Apostrophes would be significantly more problematic.

And they require a combination of two keys, pressed twice, on international keyboards.

[Shift]+['], [Shift]+['] gives you `

If you want ```, you gotta press [Shift]+['], [Shift]+['], [Shift]+['], [Shift]+['], [Shift]+['], [Shift]+[']

If your language, or any of your software, ever uses grave accents, it’s dead to me. I’m not going to do twelve key presses to mark something up

For example, multiline or highlighted code in GitHub’s markdown is ```java blablabla```. That’s [Shift]+['] [Shift]+['] [Shift]+['] [Shift]+['] [Shift]+['] [Shift]+['] [j] [a] [v] [a] [Space] (...) [Shift]+['] [Shift]+['] [Shift]+['] [Shift]+['] [Shift]+['] [Shift]+[']

That is indeed annoying.

If you use X11 (at least on Linux), and have a useless key in your layout, try to find its keycode from the output of "xmodmap -pke". If you want to enter the backtick without a modifier key, it should be the first symbol after the equals sign. Replace that symbol with "grave" and feed the whole line to "xmodmap -" (or, if you prefer, "xmodmap -e 'keycode XX = grave ...'").

This is not ideal, but I think preferable to flogging all those dead keys :)

I have no idea how to achieve the same on Windows or Mac; I suppose they have more user friendly mechanisms to remap keys.

I simply always have ` in one of my clipboards, and paste it. Using ctrl-shift-v to paste it is still easier than bashing that dead key. Still, on system start it’s not there, and I need to get it into that first, and that’s needlessly complicated.

So I avoid anything that relies on it.

> And they require a combination of two keys, pressed twice, on international keyboards.

It's a single keypress on US and UK QWERTY or Apple US-International, it's probably two keypresses on most european keyboards.

> If you want ```

In rST? Why would you want that?

> If your language, or any of your software, ever uses grave accents, it’s dead to me.

At least you get easier language choices: no bash or Z shells, no D, no Go, no Haskell, no ES6, no OCaml, no F#.

> For example, multiline or highlighted code in GitHub’s markdown

My comment is about reStructuredText, and specifically the inline external link syntax. If you want to complain about Markdown syntax may I suggest one of the markdown subthreads instead?

> It's a single keypress on US and UK QWERTY or Apple US-International, it's probably two keypresses on most european keyboards.

This is the German layout, it’s used by over 150 million people worldwide. It’s on shift-', and it’s a deadkey for using it as accent.

> At least you get easier language choices: no bash or Z shells, no D, no Go, no Haskell, no ES6, no OCaml, no F#.

In bash and ZSH I simply use other solutions for the same purpose like $() and co, and when I need it in Go or Haskell I simply have ` in my clipboard, and I don’t use the rest.

> My comment is about reStructuredText, and specifically the inline external link syntax. If you want to complain about Markdown syntax may I suggest one of the markdown subthreads instead?

Well, I’m saying this is an issue with both of them.

On my European keyboard it's just one keypress, no combo. Also nitpick: you'd probably just hold shift down for that... However I agree with your overall sentiment. I made a Sublime macro to avoid typing [```, {return}, ```, {up-arrow}] in Markdown.

Oh, do you have deadkeys disabled? That might be the cause, but generally all newer european layouts have deadkeys on, including DE since T2.

Regarding the syntax for URLs: I for one think Markdown is better here. I have seven megabytes of notes in Org mode and I still regularly mess up the order of the URL and the text.

Heh, exactly the opposite here - In Markdown I can never remember which one one gets square brackets and which one gets parens.

You shouldn't need to manually deal with links anyway. In Emacs you should be able to use C-c C-l (org-insert-link) to get a prompt for the link and the description which will then be converted to org-format for you.

I'm pretty sure I knew about that at one point, but then forgot -- possibly more than once.

Perhaps a public shaming will help me remember this time.

There are way more shortcuts in emacs than one can possibly remember.

That's why you use which-key.

`C-c C-l` is also useful if you're linking to files (org or other). You can use `M-x org-store-link` in the link destination, and a subsequent `C-c C-l` will let you add that link easily.

I use orgmode for all my notes and productivity system and can't remember ever writing a link manually in orgmode. These two shortcuts are essential. I assume similar exist for markdown and I need to learn them.

See my comment on how to remember the [[more important link][optional description]] order: https://news.ycombinator.com/item?id=15322954

Thanks, that's useful.

No word of image embedding.

Edit: Images are inlined with a link-style syntax.

  [[file:myimg.jpg]]

the thing about org-mode is that it feels strongly designed for being used inside of emacs with the emacs hotkeys etc. If you do most of your stuff in emacs that's fine. But if you like me live in the shell it's not reasonable to go so deep into emacs. I want to awk/sed/grep/vim things. And if you do that with org-mode files it won't be as much fun.

I use Markdown and just start to peek into Asciidoc.

How does Markdown or Asciidoc differ from Org in this regard?

It can be used and read in any text editor. Org is powerful, but it's more like Word than it is like notepad. It automatically formats tables, automatically copies and makes links internally, automatically indents, highlights code snippets, etc. And that's not even getting into further functions you can build with emacs lisp.

But it is centrally dependent on emacs for that power. Markdown and asciidoc work in anything.

I agree, I switched from Org-mode mainly because Emacs is not always available. Asciidoc/Asciidoctor is so much superior for plain text editing while still being consistent. Also you don't have to use Ruby implementation if Asciidoctor.js suits your needs.

you live in shell - curious what type of OS you're using for work and home.

The only non shell tools I use are browsers and Steam, the latter one painfully mostly on Windows.

Otherwise I mostly program, admin or devops around. Bash, git, vim, grep, awk, tmux, ssh are the tools I use most. Nowadays also a quite a lot of Ansible. But don't like it as much.

You know, I spent nearly 10 years really learning all that stuff with the intention to use it the rest of my life. And to this point it seems to work out quite well. So no reason to learn other tools like Emacs, which would take up another few years to learn. Once you have a basic set of tools down it's more important to use it for value production.

actually i use, vi, bash, git, grep, awk, ssh too. but emacs replaced my need for spreadsheets, calendars, todo lists, IDEs, and magit augmented my git experience. i hesitated for years on emacs, but 5 years ago i made the switch. i don't mean your setup is lacking - just open up mine )

I tried, mostly because I really like the idea of git managed sources for all these. But it's hard to integrate both bash life and emacs life. And you can't see the stuff on your phone. So I stopped after a few weeks. Any suggestions for that?

nope / still waiting for the linux on smart phones )

What features does Emacs have for editing Org-mode that makes the combo so great?

Oh I don't know, the eponymous major mode?

It really knows the elements as objects. So it can interact with them. E.g. it recognizes dates and creates a calendar like Google Calendar for you. You can also move subtrees in linked lists around, only show certain layers etc. You can turn a list element into a TODO, change it's TODO status, and even log the time you took for a TODO element. But all of that becomes much harder with bash and friends.

Do you know Powershell? It feels similar to me. You interact with objects instead of strings. That's also why string manipulation tools don't feel so great with org mode files. You cannot grab an org mode object as easily as a line or a paragraph with tools optimized for string manipulation.

I see, thank you for the explanation. I know the concept of Powershell but I haven’t really used it.

I would add that its not just that you can interact with different objects in the markup, but that there's a huge collection of operations built into Org-mode on emacs that does interact with them this way. You don't need to write code to interact with the org markdown; you just use the already written org features.

For example, the ability to search a file or set of files and collect responsive org heading items in a separate "Agenda" buffer is hugely empowering for a lot of different uses. Org-mode on emacs has both very broad and very deep functionality.

It's not necessarily easy to learn, but you can ignore the more complicated stuff if you want, just use the very simple basics and remain ignorant of the much deeper functionality that's there for people who want to make use of it. Or, better, start simple and learn more complex bits and pieces as you go; there's an active and friendly org community that helps with that.

Piles and piles of automatic formatting, for one. Working with tables in org-mode is really nice. That an emacs lisp means you can customize various parts to your liking. I used to have a snippet that would assign ids to elements automatically. I can also customize export, etc.

And, of course, like someone mentioned, being able to interact with your document almost like it's a proper data set that you can manipulate programatically.

I agree, and I'll probably never be able to shake Emacs because of my reliance on orgmode. I wouldn't leave and write markdown in another editor without many orgmode features. In fact, Emacs markdown-mode has a lot of the same features and is arguably a great markdown environment in its own right. It's annoying.

Interesting article. I have to admit to never thinking of Org-mode as a markup language unto itself.

I used Org mode a long time ago (maybe a decade) and then I switched to vim (for boring reasons) and kind of lost track of Org mode. In the meantime I started using markdown and especially github flavoured markdown for writing.

Eventually, I was looking for a TODO app and realised the Org mode gave me everything I was looking for -- and Emacs was a dramatically better UI than any other TODO app that I looked at. This got me back to Emacs (now enhanced with Evil mode which works remarkably well).

The interesting thing is that I've completely switched back to Org mode for notes. I don't even use any of the org mode features in Emacs when I'm writing. As the author of the article says, I just find it a more convenient text markup language. Sometimes I'll update org mode documents in Vim and I don't even really realise that I'm doing it because all I really want is structured documentation with folding.

However, I think for org mode to become mainstream you have to get another editor with some feature parity to Emacs. Tables are a killer feature of Org mode in Emacs. Another thing that I think is needed is better renderers outside of Emacs. Github has an orgmode renderer and it is not very good at all. I have a colleague that does all his project planning in Org mode (highly recommend, by the way) and he converts his documents to github flavoured markdown before pushing them -- which is crazy.

I'd love to see this format gain some more traction...

Yeah, as a heavy vim users who wanted org mode Spacemacs in Evil mode was all that I needed.

One thing I love with org mode is how dynamic the document is. Inserting [/] or [%] to get updated task count/percentage as TODO underneath the header is fantastic.

Are there any non-personal wikis (a wiki with user login and web-based editing) that use org-mode ?

I don't think this is exactly what you're asking, but both GitLab and GitHub render Org-mode correctly, including links. That makes for a pretty easy file-based wiki.

I always liked the sound of org-mode, but as a long time vim user, I always found attempting to learn Emacs pretty jarring (I know it's just a matter of spending more time with it, but...).

For what it's worth, I found vimwiki pretty good for personal organisation/journalling.

https://github.com/vimwiki/vimwiki/blob/dev/README.md

If you do want to jump into emacs, there is evil-mode. Just remember that it isn't trying to be vim, just feel like it.

Personally, I have found both editors too difficult to customize since I stopped using qwerty. There are just too many default keybindings. Emacs modes all map the same keys, and remapping vim has too many edge cases.

For what it's worth, I use Colemak instead of QWERTY, and just use Emacs keybindings as-is. Works great for me.

I'm the same, Colemak without any rebindings, it works just fine.

FWIW I have been using vim with Colemak for quite a few years now, with only movie remains needed to get movement back on the home row [0]

0: https://github.com/jimhester/dotfiles/blob/master/colemak/vi...

I use vim with a Dvorak keyboard. Made a few keybinding changes (about ten or so) but that's all.

Dvorak user for ~20 years now. A little over half that time was spent in vi/vim and the last ~7 or thereabouts have been emacs. Navigation in vi was weird, but I did it anyway. Otherwise I haven't found anything particularly odious in emacs.

To be clear: Vim is definitely usable using another layout, but I already had so much muscle memory with Vim using qwerty, I didn't want to relearn normal-mode at the same time as learning another layout, especially since `j` is moved to `y` in my layout (the hardest key to reach).

So I `nnoremap`ed them all, but I still have a couple of issues.

The first problem with remapping keys is that you have to remap each key again for every key that can come after the first key, i.e. to move `cw` to a different key, you have to remap `c`, and `w`. Now consider commands like `qa4caw`, and you can see it gets really hairy, really fast.

The second problem I have with remapping keys is that my qwerty `h` key is replaced with `y` in my layout, and remapping y adds a strange pause, and prevents the next command from working correctly. `w` has the same issue.

Emacs with evil-mode had a slightly better solution: I could my real layout in normal-mode, and have Emacs emulate another layout in insert-mode. Still, I would have to use qwerty as my real layout to get that to work, so it's only slightly more convenient.

Long story short: I used normal Emacs for a while since I didn't have strong muscle-memory, and the layout I use is pretty comfortable with default Emacs bindings. Emacs as an editor is quite nice anyway. Out of a mix of frustration and interest, I am working on a new editor with a more purposefully modular design, so I don't have to rely on workarounds. One of my main goals is to have "defaults" separated into separate modules rather than baked-in.

For those wondering, the layout I use is workman[0]

[0](http://workmanlayout.org/)

Interesting. I use Workman as well on my 40% keyboards (standard keyboards I use QWERTY and don't even attempt to touch type). I think learning Workman and Vim at the same time is what saved me.

I never remapped anything, I just avoid h/j/k/l (I have my arrow keys bound to the homerow) and added a bunch of bindings (F3-8, for example) that wouldn't normally be of much use to me (sitting behind the fn key on my laptop) but are also homerow-accessible.

I have transitioned to emacs + evil lately, and found that mostly seamless, but I can imagine it would have been rough if I was trying to keep QWERTY muscle memory.

I was in the same position as you. In the end, I was just happy using Spacemacs out of the box

I find reStructuredText much better option for lightweight markup as it is comparably lightweight to markdown but there is only one version, is much more powerfull, and makes more sense to me syntactically. Org-Mode looks just like another markdown to me.

> Even worse than this is the underlined heading category.

I think its the best. Compared to the prefix style it actually looks like a headline in the text document.

> The user is completely irritated for multiple reasons. Besides the tedious manual work to align the stupid heading characters with the heading title

What is tedious on typing <esc>yyp <shift>-v r # to underline current line with #?

> it is not clear what characters must be used for those heading lines. If you've got a bigger document with different levels of headings you get confused which heading character stands for which heading level.

Using a convention where bigger headlines use bigger looking characters works for me.

  H1 uses # and is both under and overlined, the rest is only underlined
  H2 uses #
  H3 uses =
  H4 uses -

I really like RST for documents that need 'a bit more' syntax than allowed by plain markdown. Especially references and so on. But then, the minimalism of bare bones markdown means that the text is very legible even without any special editor support.

> > The user is completely irritated for multiple reasons. Besides the tedious manual work to align the stupid heading characters with the heading title

> What is tedious on typing <esc>yyp <shift>-v r # to underline current line with #?

Also, there is the "easy" approach where you just fill the line instead (insert 72 #s or =s or whichever on under/over-lines). reStructuredText has a minimum fill size for a header, but not a maximum fill size.

I've drafted documents that way and then trimmed the lines down to fit the headers as a last step once they have stabilized.

Markdown/org-mode is a poor man WYSIWYG I would say.

You can easily say "this line is kind of header" but it is not human readable as it all happens inside source code editor having monospaced fonts like in this very widget I am typing the message on HN site.

Plain text blocks is plain pain in markdowns. Web platform has no concept of tabs - counting whitespaces for each line... And tables ... like 20 years ago we were doing with pseudo-graphic symbols - formatting nightmare.

That's why I've introduced "magic sequences" : https://notes.sciter.com/2017/09/09/magic-sequences-a-la-mar... - the best of two worlds - WYSIWYG but with Markdown typing twist.

WYSIWYG is kind of limiting though. I.e., I can use mermaid[1] way faster than I can use Visio. I can type out a mathematics expression way faster in TeX than I can using Word and their (greatly improved, I'll give them that) Equation Editor. Hell, I'm barely 'proficient' at the AutoDesk toolset, but I can usually out-model assemblies using their LISP interface over someone with a SpaceMouse Pro[2].

Generally though, you don't need the table or graph to be "readable" if you're the one constructing the content for others to consume, since you've already modeled the structure of the content within your head. Those -item1, -item2, --subitem1 demarcations are already internalized in your head. (Though, if we're talking about a platform for capturing data/mind-mapping/outlining/note-taking, this may not be entirely true, I admit.)

Even Adobe opts for a non-WYSIWYG DITA/SGML for their professional content management systems if only because publishing a book or magazine becomes a editorial nightmare. (In publishing, they have separations of controls just like we have separations of concerns. Our graphics and front-end guys have control over the .css and what-have-you, while our data guys will have control of the schema, and our app guys will have control of the binary; likewise, they'll have someone in charge of typesetting, someone who performs the layout management so the interstitial ads look consistent within your magazines theme or whatever, someone generating the content, and then an editor who finally signs off on it.[3]) Now that I think about it, a magazine has many source-control-management problems quite similar to what we have.

Magic sequences are pretty brilliant, I'll give you that. If it 'degrades gracefully' (i.e., when copied into a standard instance of notepad.exe or Nano, it's still grokable), that hybrid solution might be the closest panacea we have. Keep on working on that project, it has tons of interesting, orthogonal avenues to explore[4]

=====

[1] https://github.com/knsv/mermaid

[2] https://www.amazon.com/3DX-700040-3Dconnexion-SpaceMouse-Pro... Pretty much the paragon of HIDs for CAD, in my limited use. For the last 10% of touchups it's second to none, but at the project level it's still slower than using the LISP derivative once you build up a sufficient set of macros.

[3] https://en.wikipedia.org/wiki/Desktop_publishing ArborText and Framemaker Server are the two industry standards at least in my experience.

[4] I.e., take say, chemists who want to share their findings with people in their dept. Being able to design their own markup for Lewis diagrams, multiple representations of orbitals, degenerates states, etc -- then have them real time render the observed values -> a generated chart rendered in a consistent theme (a la Jupyter Notebook, but..better...) I'd imagine would be quite powerful.

WYSIWYG HTML/CSS is limited for the simple reason:

Given HTML/CSS as input you can render it precisely (produce pixels on the screen). Mathematically speaking, the task of rendering is determined.

But WYSIWYG editing essentially is an opposite task: by given/desired set of pixels to synthesize HTML/CSS structure. And that task is not determined - different HTML/CSS constructs can produce the same set of pixels. That's why there are no acceptable/usable "WYSIWYG web site editors" - WYSIWYG is feasible only on reduced scope -limited set of HTML/CSS constructs that you can use to achieve 1:1 source/rendering ratio.

And that is what Markdown is all about, again, mathematically speaking - its rendering is in 1:1 relationship with its source.

I am experimenting with Markdown too: https://notes.sciter.com/2017/09/24/markdown/

but it is far from ideal either.

Yet about mermaid ...

As any tool it is good for its purpose. De facto it is a DSL (domain specific language) in the same way as Markdown or Emacs editing system in general.

It works if creation of graphs is what you do for living. But for occasional usage (say once in a quarter or year) people usually prefer Visio - you do not need to keep in mind (limited resource) mermaid syntax - just do drag and drop - actions common to all WYSYWYG systems.

Even with Markdown - each site has its own conventions - that's why occasional users prefer WYSIWYG if it is available.

You've clearly never used org tables if you think you need to format them manually.

Also, when used in Emacs or with otherwise proper editor support, the WYSIWYG aspect is moot.

I am pretty sure that with proper tools you can achieve more or less acceptable quality. But the goal of all this tools is to provide you WYSIWYG experience. The built-in table editor in Emacs is clearly a WYSIWYG or at least close approximation of it.

But again all this is about additional tools. Main goal of Markdown & friends is to achieve at least some WYSIWYG when the only editor that you have is <textarea>.

For an idea of how amazing org-mode tables are see this youtube video:

https://www.youtube.com/watch?v=fTJVLJd_gz0

Jump to 2:20 where the table editing starts. Just wow.

I honestly don't find any of these markup languages significantly easier to use than just writing HTML.

I think the point of markup languages is not so much about convenience for writing (assuming that's what you're talking about) rather than readability in pure text form.

HTML is readable in pure text but it does not look that great.

You're right, but as soon as you introduce anything more than you could have done on a typewriter, most of these formats stop looking great pretty quickly also.

asciidoc is easily 10x easier than writing HTML. Org mode is pretty good too, but I haven't used it for very complex things, so can't make a full comparision.

Markdown and restructured text are both easier than HTML for common things, but markdown falls on its face for complicated things and rST ends up devolving into a bunch of directives that are just marginally better than HTML.

Question regarding terminology: is Org-Mode (or markdown etc.) "markup"? I thought the term "markup" comes from the ability to mark-up body text with formatting instructions, as in SGML (and thus HTML and XML). I thought it's the reason why markdown is named as it is, eg. as in "non-markup". In a generalized markup (SGML) context, markdown would be called a "wiki syntax" since SGML can parse wiki syntax into eg. HTML using short references and tag inference rules, but common use of the term may have changed from the narrower SGML definition.

[1]: https://en.m.wikipedia.org/wiki/Markup_language

Sure. Writing:

  - foo

Is the same as writing:

  <node type="list-item">foo</node>

It can be parsed identically. If you just parse it into a hash table, like {type: "list-item", value: "foo"}, then all of this becomes a non-issue. It's an intermediate format, so you can take that hash table and write it out as either of the above. You could even transpile org text into HTML and vice-versa.

What else is Markdown but body test marked with formatting instructions? Surely it doesn't matter whether emphasis is marked with asterisks or <em> tags?

It does once you need to make a numbered list where some items contain multiple paragraphs, others bulleted sub-lists, yet others images and code blocks. I'm not saying that's the best way to write a document but sometimes "port this word document to ${markup_language} for our new intranet wiki" comes from higher up and you can't question it.

The <ul> tag has one great benefit: you know exactly where the list ends, namely at the </ul> tag. Your pointy-haired boss wants a list 5 levels deep where the second paragraph of item 2.4.1 needs to be at the third level of indentation, but the second paragraph of 3.1.6 needs to be indented only twice because it belongs to the 3.1 item? With opening and closing tags you make the tree structure explicit. Edge cases like this are exactly why there are six flavours of markdown (that and egoism on its creators' part) and in some of them, getting the indentation exactly as required doesn't seem to be possible at all without chucking in HTML tags.

Your pointy-haired boss wants a list 5 levels deep where the second paragraph of item 2.4.1 needs to be at the third level of indentation, but the second paragraph of 3.1.6 needs to be indented only twice because it belongs to the 3.1 item?

FWIW Emacs solves this with text properties. You can attach a property list to any arbitrary character.

For better or worse, org mode has no such equivalent.

I see a big problems with using org-mode format with other editors than emacs, and that's why I use smth like simplified-YAML instead for notes: it doesn't lend itself well to indent-based folding (popular out-of-the-box feature in like all modern editors: Sublime, VSCode etc.).

Like, if I write

    Heading 1:
      Heading 10:
        ...
      Heading 11:
        Heading 110:
          ...
        Heading 111:
          ...

I can easily navigate a huge tree by using code folding to hide subsections. If heading levels are instead given by number of leading `*`s, then the editor really needs to be aware of the language.

(Also, backtricks are really easy to type, I see no reason to replace them with other weird characters.)

I am using org mode daily. The biggest problem is onboarding other people on the team - google docs are still easier for collaboration. Many times I wrote an initial version of the doc in org-mode and exported it to google docs for feedback and collaboration.

For example, https://tensorflight.com/tutorial is written in org and exported to HTML via theme https://github.com/fniessen/org-html-themes . People in the team were suggesting moving it to google docs.

This is nice, I pretty much already do this in my notes (like he says), except for the headings. I hate Markdown, pretty much for all the reasons he says, only I just didn't know why until now.

Similar but simpler markup is Muse: https://www.gnu.org/software/emacs-muse/

Wiki engine based on this markup: https://amusewiki.org/

I like Org-mode, but I thought the criticism against Markdown for having so many different versions was short-sighted. I'm very much reminded of this famous XKCD: https://xkcd.com/927/

The reason Markdown has so many versions is because it's been so successful and is used by so many different tools and in many different contexts. I guarantee if Org-mode became a "standard" markup language outside of Emacs that it, too, would sprout different versions.

The reason why Markdown has so many versions is that its original author was aggressively against the idea of trying to produce a spec for it, so several re-implementations went on to become their own thing.

While dialects probably would have sprouted they probably all would have supported the same core, at least, and there quite likely would be fewer of them.

Gruber also stopped development on markdown.pl a long time ago. I suspect the worthwhile innovations made by Org reimplementers would very quickly become part of org-mode as well.

What's the state of the art with library implementations of org-mode? I feel like I looked into this years ago, but I don't have my notes in front of me.

The only way I've used org-mode is the canonical Emacs implementation, which (at the time) was reason enough for some people to take up learning Emacs.

For Golang there is https://github.com/chaseadamsio/goorgeous which is also used by the static website generator Hugo to natively support .org-mode

Was thinking of C, actually. I should have specified. This could be the project for me to link C and Go, though...: C -> Go -> goorgeous

Speaking of reasonable: I always thought the use of single character markup (e.g. * for bold), visual markup (bold instead of emphasized), several modes of emphasis (italic and bold instead of just emphasized, but maybe I just used latex for too long), and excessive "simple" markup instead of some sort of language were a mistake. I personally would rather call a simplified latex + "simple" markup for the most frequently used constructs "reasonable". I also liked the approach deplate took (http://deplate.sourceforge.net/deplate.html), I would have preferred a more latex like look though.

As a long term markdown user I also don't think "reasonable" is a relevant criterion. Markdown definitely is not reasonable but it's useful.

I stop reading at the table syntax, look at asciidoc, much simpler.

Author criticises table in other formats. But look at the table, much time taken.

My markup language is the language with small effort to display what I want.

and it makes a table. I can navigate it using the tab button, it will expand columns automatically as text gets longer. It can even do some basic spreadsheet functions if you need that.

Here's a video that covers it in some depth

https://www.youtube.com/watch?v=fTJVLJd_gz0

might be a good argument, but too late? It feels like Markdown has won—look at editor preview availability, prevalence of being built into webapps, etc. For example, almost everything I write now text-wise I do in Byword, which gives me seamless sync on iOS/mac and has markdown as a first class citizen; longer writing usually gets passed through scrivener first, which has markdown as a first-class citizen, if I post a question on SO...

Markdown doesn't do tables. That's the killer for me. Yes I know I can use HTML but too much of that and I quickly get to the point of preferring HTML for the whole document. Easier to stick with just one markup format.

Github flavored markdown does do tables (in a manner that's almost equivalent to org): https://github.com/adam-p/markdown-here/wiki/Markdown-Cheats...

How ugly it is, sigh.

in a manner that's almost equivalent to org

Not really, in org-mode, you can compute columns using expressions (like in a spreadsheet) [1]. Moreover, you can feed a table to an (executable) source code block and/or you can store the output of a source code block to a table.

Just to give an example why this could be useful: suppose that you have a code snippet that produces some statistics. You can execute this snippet directly in the org-mode document and have the result in an org table. Then, you could execute another code snippet (e.g. using R) that uses the table as the input and produces a graph that is embedded inline in your org document. In GUI Emacs, you can even preview the resulting graph.

My primary criticism is that the value of org-mode documents decreases enormously outside Emacs.

[1] http://orgmode.org/worg/org-tutorials/org-spreadsheet-intro....

I still use emacs in '-nw' mode because, I don't know, I'm old, but re: your criticism, skewer-mode[1] is available. Presuming your output is targeting some form of HTML, this enables you to retain the ability to at least present your information locally (on your own file system), to colleagues (authenticate via your existing SSO or whatever), or even to a public site (via a simple git-push to via a standard httpd on a container). I'm sure there are other modes out there, (hell, you could write something from scratch in a few minutes with inotify to cater to all your specific needs). I'd say it'd be more accurate to qualify your statement as such: "the value of org-mode documents decreases as a platform to manipulate (but not distribute) your data outside of emacs"[2].

[1] https://github.com/skeeto/skewer-mode [2] And even then, modern cell phones have quad-core 1ghz ARMs on them. I was using org-mode with a P3 600, I'm sure modern phones + a Bluetooth keyboard would be sufficient to run emacs, or at least SSH + emacsclient.

To your [2] - you can run it, but legibility is kind of a problem. Also, the next Bluetooth keyboard I find that supports remapping Caps Lock to Control will be the first.

I'd say it'd be more accurate to qualify your statement as such: "the value of org-mode documents decreases as a platform to manipulate (but not distribute) your data outside of emacs"[2].

Definitely, that's what I meant. I share org stuff with ox-html or ox-latex. But colleagues cannot really use my org documents unless they are on Emacs.

What would be the guidelines to write mostly markdown compatible org files? Or is there an easy way to hack org-mode to use markdown links and formatting?

"Org-mode" has a terrible, non-memorable name so it's destined to be less popular than Markdown despite clearly being better.

I am a dedicated org-mode user and unfortunately, I feel that this is a fair critique. Never underestimate the power of branding and unconscious bias. It's a VHS vs Betamax situation. The tech with the mindshare wins the masses.

Any idea on how I might go about implementing this in Django?

I'll just leave this here:

https://xkcd.com/927/

Reply on news.ycombinator.com