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.
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]
> 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.
> 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.
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
> 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.
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..
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.
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.
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.
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)".
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.
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).
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.
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.
I did my "market study" before I started investing time for this project. I have a page on ox-hugo Documentation site (the first link in my original comment) that talks in detail why I needed to have a ox-hugo: https://ox-hugo.netlify.com/doc/why-ox-hugo/
I think org-mode is good. But I think that it and markdown could have better syntax for links. Like a link doesn't have to be wrapped in an opener or closer, since any spaces can be escaped. So you could simply do:
A 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.
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.
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.
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.
> 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.
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 :)
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)
I would second this, having written a lot of documentation recently (markdown + template + pandoc -> pdf) I am very interested in improving this workflow.
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?
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.
Readit News
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).
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
That kind of special casing is pretty much a deal-breaker. Other schemes (anyone ever heard of https?) will need that same deal.
Deleted Comment
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.
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.
Or <s TAB (or <q TAB) will create a block.
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
Deleted Comment
Open it in it's own pane with C-c ' and you can cut and paste to your heart's content.
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.
In the same spirit, one may like or hate `*` for indicating headings (the choice is really unnatural for me, always thinking of a list).
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:
Now, if you also have a description text for that link, put that afterwards.. Hope that helps.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.
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.
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.
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.
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.
IOW I just think about "inlining" the reference, which would have otherwise used [] everywhere. Feels much more regular that way around.
https://en.wikipedia.org/wiki/Squaring_the_circle
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).
Deleted Comment
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.
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/
Also, I prefer not leaving empty blank lines in between. Factors like that can change one's perception of readability.
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/
~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
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.
I'm currently trying to learn to use the time tracking functions better.
Emacs really is an OS. Linux is just my (current) kernel.
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-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
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
You can also consult Kieran Healy's guide here: http://plain-text.co (again, this targets social scientists)
That's a big one for me that I've only gotten to work in online latex tools.
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.
Other than emacs, some things have very partial orgmode implementations, but they tend to be very partial, much more different to markdown implementations.