Org Mode Is One of the Most Reasonable Markup Languages to Use for Text (2017)
karl-voit.at
karl-voit.at
In practice, org-mode in a team context barely scales because:
* it's a practically unparseable language: all interop libs (like those found for Clojure, Ruby, Haskell, etc) seem to have severe limitations parsing/emitting org-mode.
* Related to the previous point, it means one can't create .org files automatedly, from a CI pipeline. This makes it hard to have documentation guaranteedly up-to-date, out of a codebase.
* Sooner or later, at least a few people in a team won't be exactly org-mode fans (even in all-Emacs teams; I've belonged to a few).
* Lastly, github itself doesn't excel at rendering .org files - one can still find artifacts.
My take would be that if org-mode works for you - awesome! But please consider the impact of introducing it at work. Early successes can be deceiving.
I love org mode, but i think its best used by individuals. Now maybe if someone decided to standardize it, things would be different, but as it stands, don't use it on teams.
However, for your own, personal stuff, i think its great. For example I use org-roam to manage my knowledge base. This is an inherently personal pursuit so I'm not worried about using it for this purpose.
I think it would be cool to have a format comparable to Markdown but with support for a JSON-like object notation that supports the linking of any metadata to any part of the text. That would make it simpler and let users add their own properties which would then be just ignored by other parsers.
The problem with such things is of course that we already have what feels like a hundred different Markdown variants, each one slightly different and incompatible with the others in some way. That is in fact the reason I started using .org in the first place as a Vim user (that and the LaTeX code support).
Org can look cumbersome, but only in documents that I posit would be cumbersome in any format.
Though, I suspect that down that road ultimately leads to some form of xml with cdata style escapes for thorns.
Xml is at least a markup language. Json is not. Encoding a document with it is terrible. Just look at Jupyter some time.
Or just... Hyperlinks in general. What would you use json to encode that https://foo/baz shouldn't already handle? And, if you ack that links are already links, the standard of either [display](link) or [[display][link]] seems as nice as json could possibly get.
Hyperlinks and text styling can still be done with the usual methods, though I don't quite like how in md/org I constantly forget where the label and the url goes in the hyperlink syntax. Also some of the text styling could use slight modifications to reduce the need for escaping.
I'm not saying Org-Mode lacks major features or anything, I'm just the kinda guy who likes to tinker and experiment with new ideas.
I'm not really seeing any benefit that json or the like would bring to the table here. I could almost see a benefit to not having different ways to make properties, but only a little. Since it is basically just a mark that is intended to indicate different types of marked up text.
As an example, if moved to json, how would you distinguish the likes of an example block? Just a json header with no closing tag? Or a json header with another json close?
I guess, put more directly. Orgmode is a bit of an adhoc markup language. The designating tags to start and end a block are typically $+BEGIN_FOO and #+END_FOO. With free text between them, and a lot of magic from emacs to syntax highlight based on FOO. Unless you are just going to change to {"BEGIN":"FOO"} and {"END:"FOO"}, with free text between, you are forcing human edited text into a json field, and that is what makes me cringe. And if that is your end goal, {"BEGIN":"FOO"} is actually a chore to type and read.
Yes, it composes somewhat nicely such that
#+NAME: Example
#+BEGIN_SRC lisp
(+ 3 2)
#+END_SRC
{"NAME":"EXAMPLE", "BEGIN": "src", "lang": "lisp"}
(+ 3 2)
{"END":"src"}
#+STARTUP: indent
#+OPTIONS: ^:nil
{ "STARTUP" : ["indent"], "OPTIONS" : { "^":null} }
I disagree that it's less clunky than the present situation, but it may be more consistent. I mean, you'd still need something to mark that some JSON follows and is separate from the other text in the document.
#+CONFIG: <JSON String>
But yes, we are in agreement. It wouldn't be much better for someone typing directly into org files. It's the same reason markdown and other formats get translated into HTML, heavyweight markups are annoying to type, even if consistent. It might be better for tooling around org-mode, but at that point you're pushing away from org files as plaintext entities meant to be directly edited and towards them being serialization formats you interact with through other programs.
In the worst case scenario, you should be able to just use the elisp code itself to parse the file. There already are exporters to most other common formats.
1. Give a header an id and jump to it from anywhere.
2. Attach scheduling information to the header so that you can easily track TODOs and DONEs. I usually further break down a TODO into several sub-TODOs and write something under each one to organize my thoughts, including code blocks, tables, quotes, footnotes, which is impossible in Markdown.
3. You can attach anything else to it, too. I also attach an Anki note ID to it and use Org Mode as an alternative Anki editing environment. Because of the attached note ID, I can easily distinguish whether I want to create a new Anki card (without an ID) or update an existing one (with an ID). That is also hard to implement in Markdown (Strictly speaking, I don't think it's even possible to implement it in Markdown).
My only complaint is that Emacs is the only text editor that fully supports Org Mode. Other editors (e.g. vim, VSCode) support it too, with only to an extent.
Sometimes I also wonder why Org Mode is not as popular as Markdown, the former is far more powerful.
Because it's so integrated with Emacs, and all other editors are second class citizens (/hosts)?
My org files quickly accumulate custom elisp snippets for automating small one-off things like rendering embedded dot with Graphviz and displaying them inline. I don't think I'm alone in that. Unfortunately, that creates a situation where, whenever I try to work with org files in other editors, there's a certain "it's like opening Photoshop files in MS Paint" aspect to the experience. Too many things that I've come to take for granted about how I'd interact with and edit these files no longer works.
Markdown, on the other hand, is just a markup format. It has lots of dialects, but it isn't really owned by anyone. That creates a very different power structure: Markdown editors are free to just try to make a good Markdown editing/viewing experience, whatever that means to that particular editor's developer. There's no looming and inevitably unfavorable comparison to the format's native editor to have to contend with.
I suspect that I can write embedable applications in JS and load them as libraries in Markdown to perform advanced stunts, like in Org mode.
But jokes aside, is there something that doesn't let us implement a language server for org mode?
%%(org-anniversary 2021 11 18) It's been %d years since the 50,000th org-mode thread on HN.
https://orgmode.org/manual/Environment-of-a-Code-Block.html
That's a lot more than markup at this point since you can run those inside of org-mode.
/s
It doesn't. There have been failed efforts in standardizing the grammar. If they can't even do that, it's clear that being standalone is not a goal.
Instead of org mode, I bought a markdown editor for iOS and use that. Then I sync the markdown files to my computer using iCloud.
Even has system-wide note capture via system drawer which makes jotting notes and ideas very efficient. Something I need to figure out with rofi + org-capture or similar for desktop!
My concern with org-mode is a superset of that. The only parser that fully supports org-mode is the one in org-mode itself. The ones not built into org-mode (pandoc, org-ruby, etc) all only support a subset of org's features. This makes writing anything to share in org-mode more difficult because you have to restrict yourself to writing in the subset of org-mode that e.g. pandoc supports.
That's why I laughed quietly to myself when I saw that the author had written, "Org mode is standardized". Org-mode is exactly as standardized as Markdown was when Gruber published Markdown.pl. There is one authoritative implementation (org-mode's elisp, Gruber's perl script), and to be "standard", all other implementations need bug-for-bug compatibility with the authoritative version. The only reason org-mode feels more standardized is that, currently, the only practical way to use org-mode is with the original implementation, in emacs. No doubt the original users of Markdown felt the same way, when using markdown.pl to format their blog posts.
Powerful seems to imply complicated to implement. Same reason why markdown is beating asciidoc in everything.
The reliance on Emacs has been mentioned by a fair number of commenters already, but there's also another issue here, I think -- there are a lot of Markdown variants, and while that's usually described as a flaw rather than a feature, the silver lining is that there probably is a Markdown processor that can handle [thing that you want], from citations to cross-references to math formulas. "But then I'm tied to that variant of Markdown" is a valid objection, but it's not one that's really answered by Org Mode.
In practice, some Markdown syntax that started as "non-standard extensions" -- most notably tables and footnotes -- has been widely adopted by most processors. Several processors I know of do have ways to attach labels or other metadata to sections, such as MultiMarkdown's cross-references.
> I usually further break down a TODO into several sub-TODOs and write something under each one to organize my thoughts, including code blocks, tables, quotes, footnotes, which is impossible in Markdown.
This one I'm not actually sure I'm following. You can certainly insert code blocks, tables, quotes, and footnotes under subheadings and even under indented lists.
Org Mode is absolutely better as a task manager and day planner -- but that's not a function of Org Mode's markup syntax, except to the degree the syntax has specific features for supporting tasks and agendas. It's a function of Org Mode being, well, a mode, with a lot of specific functionality in Emacs. For general purpose document markup, it's probably as good as (e.g.) MultiMarkdown, but not better; if you're comfortable with one, there'd be little obvious reason to switch to the other.
Markdown is plain text at one end of the complexity continuum. Microsoft Word is towards the other end. Org-mode is somewhere in-between.
You can replace "Org Mode" with almost every single markup language out there. Markdown was designed from the start as an 80% solution, and RST, asciidoc, &c. are all more powerful than markdown. For interchange, popularity begets popularity, so it would be surprising if the technically best (in isolation) solution won.
I only picked up emacs last year after being a die-hard vim user for 8+ years and org-mode was a large reason why. I wanted to learn how to manage todos and documentation alongside my code - it's incredible. Lifechanging.
The only negative is trying to teach others to use this workflow. I haven't found a tool yet that can easily transform todos in org-mode into something a product manager could use. Exporting to HTML makes sharing docs a breeze. Maybe workflow tools are a rarer use-case or I just haven't dug far enough.
Either way, org-mode definitely worth learning in 2021
Sharing docs via HTML export is great
On the one hand you just have a humanly-readable plain text file. On the other it is also a spreadsheet. On the other it is also the interface to a complex Gannt chart. Org files are multidimensional; Markdown files can merely be exported to a variety of formats.
=head1 This is a major headline
=head2 And a secondary one.
Paragraphs end with blank lines, as with
many other markup systems.
And you can use I<emphasize> B<Text> with inline
codes, including some richer than the usual italics/bold,
like e.g. for F<filenames.txt>.
Rebol's MakeDoc also was quite neat, and had a very minimal implementation. Man, so much lost potential with that language.
That's why I like Textile and Markdown so much. If I'm going to type out all the overhead tags, just like me go full-on LaTeX.
Which is a shame. I think Jupyter mainly steals a ton of market from Mathematica and Matlab, without most of it's users ever having seen those offerings. Org has the advantage that it is not tied to any specific extension language. It is all a cdata style delimited text block with contacts on environment setup and tear down. With the output being fair have for editing.
But what I would want to use it for is literate programming, at least for my own personal projects.
Or at the very least as a jupyter notebook replacement (python-mode + elpy is already a decent enough replacement ATM).
One day I'll set things up properly.
I am yet to use tangle for anything real like dotfiles or such.
I work a fair bit with AWS, and the command line utility can output results in JSON. Being able to reference and mess with that output in org-babel and org-mode tables would be great.
[1] as in, you need to build it yourself from HEAD.