CODEWITHSUNDEEP
emacsexportmarkdownorg-mode
barrios
barrios

Reputation: 1124

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

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?

Upvotes: 4

Views: 3871

Answers (4)

Whil
Whil

Reputation: 491

A few year later...

But my solution to this problem, that I also just experienced, was to modify the function org-md-inner-template in ox-md.el. This was done by adding a few lines, mimicking what exists for the same purpose in ox-html.el. After that, regular markdown exports will include the title if org-export-with-title is not nil.

The following is the modified function that will allow the title (and subtitle) to be exported to markdown as a level 1 heading:

(defun org-md-inner-template (contents info)
  "Return body of document after converting it to Markdown syntax.
CONTENTS is the transcoded contents string.  INFO is a plist
holding export options."
  ;; Make sure CONTENTS is separated from table of contents and
  ;; footnotes with at least a blank line.
  (concat
   ;; Potential title as lvl 1 heading
   (let ((title (and (plist-get info :with-title)
                     (plist-get info :title)))
         (subtitle (plist-get info :subtitle))
         (style (plist-get info :md-headline-style))
         (level 1))
     (when title
       (org-md--headline-title
        style
        level
        (format "%s%s"
            (org-export-data title info)
                (if subtitle
                    (format " - %s" (org-export-data subtitle info))
                  "")))))

   ;; Table of contents.
   (let ((depth (plist-get info :with-toc)))
     (when depth
       (concat (org-md--build-toc info (and (wholenump depth) depth)) "\n")))

   ;; Document contents.
   contents
   "\n"
   ;; Footnotes section.
   (org-md--footnote-section info)))

Upvotes: 0

adolflow
adolflow

Reputation: 49

This is useful to get what the answer expects but I think it is not the right path to resolve this question. Let me explain it

I think the issue is about exporting options from org-mode to md but I also want to keep my docs in org-mode and this hacks org-mode export option adding another line for title exporting to md headline 1 but not manages the whole thing.

What I expect and I guess this is the important issue is to export orgmode to md properly, I mean:

  • the title from orgmode to md heading one (#) -as orgmode to html does.

  • the heading one from orgmode (*) to md heading two (##)

If this issue is not about it I should open a new one :)

Best!

Upvotes: 1

fniessen
fniessen

Reputation: 4506

See http://article.gmane.org/gmane.emacs.orgmode/82634.

The problem is supposed to be fixed. Only waiting for an update of the converter on GitHub site...

Upvotes: 1

itsjeyd
itsjeyd

Reputation: 5280

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

Upvotes: 7

Related Questions