Emacs org-mode markdown export: #+TITLE option not exported

Question

I use the great org-mode to easily push modifications of README.md to GitHub projects. Markdown export works great, except for the #+TITLE option not being exported to Markdown - which works flawlessly for HTML export.

I want to keep the file name README.org for convenient converting to Markdown, else I could have chosen the title as file name, which displays the title correctly on GitHub.

Any suggestions on how to achieve this?

Answer 1

Based on your question and subsequent comments, you seem to want to achieve three things:

1. Define a custom title that gets exported as a top-level headline.

2. Insert the TOC after the title.

3. The TOC should not include the title.

---

Custom location for TOC

Inserting the TOC at a custom location is easy, so let's start with that: Add

#+OPTIONS: toc:nil

to the export options at the top of README.org. By itself, this tells org-mode not to include the default TOC when exporting. You can then place the TOC where you want it to go by inserting

#+TOC: headlines

at the desired location. (This method is not specific to Markdown export.)

---

Custom title that doesn't show up in TOC

Defining a custom title that is not included in the TOC is a bit trickier, but the basic idea is to exclude the title from the TOC by formatting it as a Markdown headline instead of an org headline. As a first step, change README.org to look like this:

#+OPTIONS: toc:nil

# Emacs als Python-Power-Editor für den RasPi

#+TOC: headlines

* Wieso nur ausgerechnet Emacs???
...

Out of the box this won't yield the desired results because org will interpret the title as a comment and by default the Markdown exporter is configured to ignore comments. However, in order to change the default behavior you can

1. define a custom transcoder for comments in your .emacs:

   (defun org-md-comment (comment contents info)
     "Transcode COMMENT object into Markdown format.
   CONTENTS is nil.  INFO is a plist holding contextual information."
     (format "# %s" (org-element-property :value comment)))
   

2. redefine the Markdown export backend to make use of this transcoder:

   (org-export-define-derived-backend 'md 'html
     ;; ...
     :translate-alist '((bold . org-md-bold)
                        (code . org-md-verbatim)
                        (comment . org-md-comment) ;; <--- Use custom transcoder
                        (comment-block . (lambda (&rest args) ""))
                        ;; ...
                        ))
   

   The original definition of the backend can be found in the file ox-md.el; this file is located in the directory of your org-mode installation. You'll need to copy the full definition to your .emacs file and change the line

   (comment . (lambda (&rest args) ""))
   

   as shown above.

---

Results

With these customizations the resulting README.md file looks like this:

# Emacs als Python-Power-Editor für den RasPi

<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#sec-1">1. Wieso nur ausgerechnet Emacs???</a></li>
<li><a href="#sec-2">2. Die Maus ist tot, es leben die shortcuts!</a></li>
<li><a href="#sec-3">3. Auf den Emacs, fertig, los!</a></li>
</ul>
</div>
</div>

# Wieso nur ausgerechnet Emacs???
...