Table of Contents

• Does it make sense to talk about Org Mode instead of Markdown?
• The export problems
• The solution: export from Org-Mode to Markdown via Pandoc with GFM option.
• The special case of exporting code blocks.

Does it make sense to talk about Org Mode instead of Markdown?

Why should I use Org-Mode to write articles to be published network inMarkdown format?

Wouldn’t it be more convenient to write the articles directly inMarkdown?

The question is more than justified and the answer is not obvious.

First, let me remind you that Org-Mode is a mode of GNU/Emacs. Whilethere are various plugins for other editors, including Vim, none of themcan match the outstanding efficiency of the original system.

So: to write in Org-Mode, it’s best to must use GNU/Emacs.

Org-Mode is a complete and extremely powerful structured writing system,although the learning curve is significantly upward.

It is a very useful resource for anyone who has to write complexdocuments, such as legal documents, scientific publications, novels.

Markdown is a language with text-format syntax much easier and immediateto learn.

However, some current CMSs directly accept Markdown format without theneed for any conversion. I am not aware, however, that it is possible topublish directly in Org-Mode format.

Org-Mode (in Emacs, of course) has a very extensive set of commands formoving, shifting, deleting chapters, and managing images and is,therefore, extremely useful in the creative and construction phase ofthe writings.

In summary: Org-Mode is a very powerful, fast and effective writingsystem for all those who write complex documents by profession orpassion.

But sooner or later, you will need to convert the material from Org-Modeto another format for printing (LaTeX) or web publishing (Markdown orHTML) (or both).

The export problems

Org-Mode has excellent and very fast built-in export capabilities with amyriad of options and configurations to various formats including LaTeX,HTML, and Markdown itself.

The export result is excellent for LaTeX, HTML, and basic Markdown.

However, basic Markdown lacks some syntactic features compared to theGFM dialect (i.e., “GitHub Flavored Markdown”).

For example, as I witnessed directly in the course of preparing one ofmy articles, Org-Mode’s internal export produces tables in HTML format(i.e., with the typical <table>, <tr> and <td> tags) instead ofthe dedicated Markdown GFM table markup code.

Using Pandoc with the standard configuration (such as“Pandoc input_file -or output_file”) the result is better but stillnot enough, as we will see in the examples below.** Some examples tomake it clearer

I report some export examples from the Org-Mode version of this articleof mine.

The following table is the “source” text version in Org-Mode:

| Function | Keystrokes ||--------------------------------+------------|| | <c> || Delete Surrounding Command | =dsc= || Delete Surrounding Environment | =dse= || Change Surrounding Command | =csc= || Change Surrounding Environment | =cse= |

This is the result of exporting via Org-Mode built-in function:

 <table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides"><colgroup><col class="org-left" /><col class="org-center" /></colgroup><thead><tr><th scope="col" class="org-left">Function</th><th scope="col" class="org-center">Keystrokes</th></tr></thead><tbody><tr><td class="org-left">Delete Surrounding Command</td><td class="org-center"><code>dsc</code></td></tr><tr><td class="org-left">Delete Surrounding Environment</td><td class="org-center"><code>dse</code></td></tr><tr><td class="org-left">Change Surrounding Command</td><td class="org-center"><code>csc</code></td></tr><tr><td class="org-left">Change Surrounding Environment</td><td class="org-center"><code>cse</code></td></tr></tbody></table>

The code is pure HTML and not Markdown.

This, on the other hand, is the result of exporting with Pandoc usingthe following formula:

pandoc -s nomefile.org -o nomefile.md

Function Keystrokes-------------------------------- ------------------Delete Surrounding Command dsc{.verbatim}Delete Surrounding Environment dse{.verbatim}Change Surrounding Command csc{.verbatim}Change Surrounding Environment cse{.verbatim}

The code seems to be correct but the result on browser is very differentfrom the desired one:

 Function KeystrokesDelete Surrounding Command dsc{.verbatim} Delete Surrounding Environment dse{.verbatim} Change Surrounding Command csc{.verbatim} Change Surrounding Environment cse{.verbatim}

The solution: export from Org-Mode to Markdown via Pandoc with GFM option.

The solution is to convert from Org-Mode to Markdown using Pandoc butadding the GFM option to have the code “enriched” from the base version.

This is the pattern, found, after long search, on thispage:

pandoc --from=org --to=gfm org-mode-file.org > markdown.md

where, of course, the document names org-mode-file.org andmarkdown.md must be replaced with the real ones.

Note the “--to=gfm” option that determines the output in the MarkdownGitHub format.

Applying that pattern to the code mentioned in the previous paragraphproduces the following converted code:

| Function | Keystrokes ||--------------------------------|:----------:|| Delete Surrounding Command | dsc || Delete Surrounding Environment | dse || Change Surrounding Command | csc || Change Surrounding Environment | cse |

In this way, you get perfectly formatted Markdown code even for theparts not provided in the basic version.

Note, in addition to the complete table of each character, also the“centering” of the second column.

Then, you can create the writings by taking advantage of the infinitepotential of Org-Mode and, then, exporting them to HTML or Markdown (orLaTeX) perfectly formatted for the publishing stage.

The special case of exporting code blocks.

While testing this topic I found a peculiarity in the export of sourcecode (tag src).

Simply using the combination “begin_src ... end_src” gives a result inMarkdown as if it were the “quote” format, that is, with four indentspaces (which is equivalent to prefixing “>” before each line).

In exporting via Pandoc, the same result is obtained ONLY if thefragment language is not specified.

If, however, the language is specified (for example:“#+begin_src markdown”) the export is correctly formatted as a codeblock with the same language specified in Markdown.

The names of the languages allowed by Org and Markdown are not, however,coincident.

This, however, does not preclude the correct formatting of the code whenexporting, but only the colored display of the content: if the languageindicated in Org-Mode were not provided in Markdown it would simplyresult in an uncolored fragment but, in any case, correctly exported asa “code block” and not as a “citation block.”

Thank you for your attention.