
Org-Mode Is One of the Most Reasonable Markup Languages to Use for Text - pmoriarty
http://karl-voit.at/2017/09/23/orgmode-as-markup-only/
======
WalterBright
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.
        ```

~~~
1wd
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](http://www.wikicreole.org/wiki/Creole1.0)
[2]
[https://en.wikipedia.org/wiki/Creole_(markup)](https://en.wikipedia.org/wiki/Creole_\(markup\))
[3] [https://i.imgur.com/zbkU670.gif](https://i.imgur.com/zbkU670.gif)

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

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

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

~~~
Terretta
"squared circle" = []()

[https://en.wikipedia.org/wiki/Squaring_the_circle](https://en.wikipedia.org/wiki/Squaring_the_circle)

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

------
throwawayknecht
> 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/bjonnh/PyOrgMode/issues/39)
,
[https://github.com/hsitz/VimOrganizer/issues/78](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.

------
kaushalmodi
Shameless plug: [https://ox-hugo.netlify.com](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/](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...](https://gitlab.com/kaushalmodi/kaushalmodi.gitlab.io/raw/master/content-
org/notes/string-fns-nim-vs-python.org), 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/](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/](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.

~~~
bastijn
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/](http://commonmark.org/)

~~~
kaushalmodi
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...](https://ox-hugo.netlify.com/images/ox-hugo-doc-source-viewing-in-
Termux-Android.png)

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

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

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

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

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

~~~
juki
`#+...` 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...](http://orgmode.org/worg/dev/org-
syntax.html#Affiliated_keywords)

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

------
MarcScott
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](https://github.com/yjwen/org-reveal) which let's me make slide decks
effortlessly.

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

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

------
Schiphol
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?

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

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

~~~
jboynyc
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](http://wcm1.web.rice.edu/plain-text-citations.html)

------
sfifs
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?

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

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

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

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

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

~~~
Moyamo
> 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?

~~~
geokon
"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

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

~~~
danieldk
_\- 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/](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.

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

------
gavinpc
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!

~~~
ChrisSD
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](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.

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

~~~
WorldMaker
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.)

------
peterburkimsher
\+ 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.

~~~
juki
> 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+`).

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

+88673630588+63377

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

~~~
Jaruzel
Why is strikethrough not a minus sign?

i.e. -strikethough-

~~~
juki
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).

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

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

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

~~~
kaushalmodi
> 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
"&ndash;" or "&#8211;".

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.

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

------
vanderZwan
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/](https://casual-effects.com/markdeep/)

------
theodorewiles
shameless plug: [https://github.com/theodorewiles/org-mind-
map](https://github.com/theodorewiles/org-mind-map)

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

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

~~~
alanh
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.)

~~~
maemre
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](http://orgmode.org/manual/Footnotes.html)

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

~~~
todd8
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).

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

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

~~~
giggles_giggles
#+INCLUDE

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

~~~
throwanem
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!

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

~~~
throwanem
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!

------
masklinn
> `Text <[http://example.com/>`_](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.

~~~
kuschku
> 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]+[']

~~~
masklinn
> 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?

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

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

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

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

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

~~~
xfer
That's why you use which-key.

------
some1else
No word of image embedding.

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

    
    
      [[file:myimg.jpg]]

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

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

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

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

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

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

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

~~~
vvanders
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_.

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

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

------
KhalPanda
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](https://github.com/vimwiki/vimwiki/blob/dev/README.md)

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

~~~
thomastjeffery
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/](http://workmanlayout.org/))

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

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

~~~
tenken
WUSIWUG...WYSIWYG?

~~~
coldtea
[http://acronyms.thefreedictionary.com/WUSIWUG](http://acronyms.thefreedictionary.com/WUSIWUG)

------
c-smile
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...](https://notes.sciter.com/2017/09/09/magic-sequences-a-la-markdown/) \-
the best of two worlds - WYSIWYG but with Markdown typing twist.

~~~
iheartmemcache
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](https://github.com/knsv/mermaid)

[2] [https://www.amazon.com/3DX-700040-3Dconnexion-SpaceMouse-
Pro...](https://www.amazon.com/3DX-700040-3Dconnexion-SpaceMouse-
Pro-3D-Mouse/dp/B006GPZ17K/) 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](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.

~~~
c-smile
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/](https://notes.sciter.com/2017/09/24/markdown/)

but it is far from ideal either.

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

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

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

------
tannhaeuser
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](https://en.m.wikipedia.org/wiki/Markup_language)

~~~
Sharlin
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?

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

~~~
sillysaurus3
_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.

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

------
kozikow
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](https://tensorflight.com/tutorial) is
written in org and exported to HTML via theme
[https://github.com/fniessen/org-html-themes](https://github.com/fniessen/org-
html-themes) . People in the team were suggesting moving it to google docs.

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

------
ycmbntrthrwaway
Similar but simpler markup is Muse: [https://www.gnu.org/software/emacs-
muse/](https://www.gnu.org/software/emacs-muse/)

Wiki engine based on this markup:
[https://amusewiki.org/](https://amusewiki.org/)

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

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

~~~
bch
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

------
stewbrew
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](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.

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

~~~
stinkytaco
The power of tables in org is the automatic formatting. I type
|Name|Address|Something Else| and jump to the next line and put in a |-

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](https://www.youtube.com/watch?v=fTJVLJd_gz0)

------
fsiefken
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?

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

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

------
hn_throwaway_99
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/](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.

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

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

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

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

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

~~~
hellabites
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...](https://github.com/adam-p/markdown-here/wiki/Markdown-
Cheatsheet#tables)

~~~
danieldk
_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....](http://orgmode.org/worg/org-tutorials/org-spreadsheet-intro.html)

~~~
iheartmemcache
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](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.

~~~
danieldk
_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.

------
PDoyle
I'll just leave this here:

[https://xkcd.com/927/](https://xkcd.com/927/)

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

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

