Converting from Org Mode to Markdown GFM

Converting from Org Mode to Markdown GFM

1. 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 in Markdown format?

Wouldn't it be more convenient to write the articles directly in Markdown?

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. While there are various plugins for other editors, including Vim, none of them can 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 complex documents, such as legal documents, scientific publications, novels.

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

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

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

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

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

2. The export problems

Org-Mode has excellent and very fast built-in export capabilities with a myriad 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 the GFM dialect (i.e., "GitHub Flavored Markdown").

For example, as I witnessed directly in the course of preparing one of my articles, Org-Mode's internal export produces tables in HTML format (i.e., with the typical <table>, <tr> and <td> tags) instead of the 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 still not enough, as we will see in the examples below.

3. Some examples to make it clearer

I report some export examples from the Org-Mode version of this article of 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 using the 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 different from the desired one: 

  Function Keystrokes

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

4. 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 but adding the GFM option to have the code "enriched" from the base version.

This is the pattern, found, after long search, on this page: 

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

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

Note the "--to=gfm" option that determines the output in the Markdown GitHub format.

Applying that pattern to the code mentioned in the previous paragraph produces 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 the parts 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 infinite potential of Org-Mode and, then, exporting them to HTML or Markdown (or LaTeX) perfectly formatted for the publishing stage.

5. The special case of exporting code blocks.

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

Simply using the combination "begin_src ... end_src" gives a result in Markdown as if it were the "quote" format, that is, with four indent spaces (which is equivalent to prefixing ">" before each line).

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

If, however, the language is specified (for example: "#+begin_src markdown") the export is correctly formatted as a code block 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 when exporting, but only the colored display of the content: if the language indicated in Org-Mode were not provided in Markdown it would simply result in an uncolored fragment but, in any case, correctly exported as a "code block" and not as a "citation block."

Thank you for your attention.

Originally published at https://francopasut.netlify.app

Comments

Post a Comment

Popular posts from this blog

Vim: searching for text containing a slash or a question mark

Vim: searching for text containing a slash or a question mark Vim: the search command To activate a text search in Vim, press one of the following trigger keys in your keyboard: the slash "/" key (do not confuse with the back-slash "\" key) the question mark key. By pressing the slash "/" key will activate a forward search. By pressing the question mark "/" key will activate a backward search. To move the cursor to the results in your document, press the "n" key (mnemonic for “ next ”). To invert the direction of the cursor, press the "N" key, (“upper n”) . What about if you need to search for a slash or a question mark , i.e. the same trigger characters , in your document? You can prepend the Escape character to the trigger key. The Escape character The Escape character is the back-slash key: "\" . Just an example: if you need to forward search (then with / trigger k...
Read more

Vim: Cut, Copy and Paste to and from the system clipboard

Image
Vim: Cut, Copy and Paste to and from the system clipboard Table of Contents 1. Cut, Copy and Paste using the computer keyboard 2. Vim and the clipboard 3. From Vim to the Clipboard 4. From the Clipboard to Vim 5. Some key shortcuts in gVim Figure 1: Vim 1 Cut, Copy and Paste using the computer keyboard Everybody knows how to use the keyboard combinations Ctrl-c , Ctrl-x , and Ctrl-v in Windows and Linux (or Cmd-c , Cmd-x and Cmd-v in macOS) to copy, cut and paste text across applications. Many think that those combinations are universal and work with any application. But Vim and gVim are different, they use another system to exchange information with the rest of the IT world. For example, in Vim under Linux, the key combination Ctrl-v corresponds to the visual block function and does not affect the pasting text. I wrote this article to remind me, as a non-programmer, the key combinations to be used in the Vim world to sha...
Read more