Re: [O] ox-md.el: Export TOC and Footnotes as Markdown rather than HTML

[Jake Romer]

Hi Nicolas,

Thanks for the quick feedback! Notes on your notes:

 

However, AFAIU, rendering for footnote section is still HTML, albeit a lightweight one.

Ah yes, that's true—the enclosing section can be rendered in Markdown, but the footnotes themselves (and their references) are in HTML. I think that make sense because footnotes, afaik, aren't part of "vanilla" Markdown, although some variants do support them.

I think this function should not be specific to footnote section header, i.e., it could factor out the following code in `org-md-headline'

Good point -- I implemented this in the attached revision.

Ideally, this should handle the level and a scope so as to handle toc:3 or #+TOC: headlines local.

I'm not as familiar with Org's TOC facilities as I should be, so I'll update to handle these cases after some research. I want to avoid letting these patches get too big, too.

Here's the patch for generating the footnotes section as Markdown, let me know what you think.

Cheers,

Jake

On Mon, Aug 8, 2016 at 9:35 AM, Nicolas Goaziou <address@hidden> wrote:

Hello,

Jake Romer <address@hidden> writes:

> I notice that in Org 8.3, `org-md-export-as-markdown` and
> `org-md-export-to-markdown` render a document's Table of Contents and
> Footnotes sections as HTML rather than Markdown.

Correct.

> I have a couple of patches that change this behavior so that both are
> rendered as Markdown. I'd love to hear any thoughts or suggestions for
> improvement if you think this would be useful to include in ox-md.el.

That's very interesting. Thank you. Some comments follow.

However, AFAIU, rendering for footnote section is still HTML, albeit
a lightweight one.

> From b64d21e6b5bb35b6446abf37233463e40df040c3 Mon Sep 17 00:00:00 2001
> From: Jake Romer <address@hidden>
> Date: Sun, 7 Aug 2016 16:04:39 -0400
> Subject: [PATCH 1/2] Export Footnotes section as Markdown

The commit message has to contain the name of new and modified
functions. See commit log for examples.
>
> ---
>  ox-md.el | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  1 file changed, 72 insertions(+), 2 deletions(-)
>
> diff --git a/ox-md.el b/ox-md.el
> index 0aaade6..865e123 100644
> --- a/ox-md.el
> +++ b/ox-md.el
> @@ -50,6 +50,20 @@ This variable can be set to either `atx' or `setext'."
>         (const :tag "Use \"atx\" style" atx)
>         (const :tag "Use \"Setext\" style" setext)))
>
> +;;;; Footnotes
> +
> +(defcustom org-md-footnote-format "^%s"
> +  "The format for the footnote reference.
> +%s will be replaced by the footnote reference itself."
> +  :group 'org-export-md
> +  :type 'string)
> +

> +(defcustom org-md-footnote-section-title "Footnotes"
> +  "The title for the Footnotes section.
> +Example: `Footnotes', `References', `Sources', etc."
> +  :group 'org-export-md
> +  :type 'string)

I suggest to ignore the variable above and use an equivalent of

   (org-html--translate "Table of Contents" info)

instead.

> +(defun org-md-footnote-section-header (info)
> +  "Renders a template for the footnotes section header in the preferred style.
> +INFO is used as a communication channel."
> +  (let ((style (plist-get info :md-headline-style))
> +        (section-title (plist-get info :md-footnote-section-title)))
> +    (cond
> +     ((equal style 'atx) (format "\n%s %s\n%%s\n" "##" section-title))
> +     ((equal style 'setext) (format "\n%s\n%s\n%%s\n"
> +                                    section-title
> +                                    (make-string (length section-title) ?-))))))

(if (eq style 'atx)
    ...
 ...)

I think this function should not be specific to footnote section header,
i.e., it could factor out the following code in `org-md-headline'

       ;; Use "Setext" style.
       ((eq style 'setext)
        (concat heading tags anchor "\n"
                (make-string (length heading) (if (= level 1) ?= ?-))
                "\n\n"
                contents))
       ;; Use "atx" style.
       (t (concat (make-string level ?#) " " heading tags anchor "\n\n"
                  contents))

> +;;;; Footnotes Section
> +
> +(defun org-md-footnote-section (info)
> +  "Format the footnote section as Markdown.
> +INFO is a plist used as a communication channel."
> +  (let* ((fn-alist (org-export-collect-footnote-definitions info))
> +         (fn-alist
> +          (loop for (n type raw) in fn-alist collect
> +                (cons n (org-trim (org-export-data raw info))))))
> +    (when fn-alist
> +      (format
> +       (org-md-footnote-section-header info)
> +       (format
> +        "\n%s\n"
> +        (mapconcat
> +         (lambda (fn)
> +           (let ((n (car fn)) (def (cdr fn)))
> +             (format
> +              "%s %s\n"
> +              (format
> +               (plist-get info :md-footnote-format)
> +               (org-html--anchor
> +                (format "fn.%d" n)
> +                n
> +                (format " href="" n)
> +                info))
> +              def)))
> +         fn-alist
> +         "\n"))))))
> +
> +
>  ;;;; Template
>
>  (defun org-md-inner-template (contents info)
> @@ -474,7 +536,15 @@ 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.
> -  (org-trim (org-html-inner-template (concat "\n" contents "\n") info)))
> +  (let* ((depth (plist-get info :with-toc))
> +         (headlines (and depth (org-export-collect-headlines info depth)))
> +         (toc-string (org-html-toc depth info))
> +         (toc-tail (if headlines "\n\n" ""))
> +         (footnotes (org-md-footnote-section info)))
> +    (org-trim (concat toc-string
> +                      toc-tail
> +                      contents
> +                      footnotes))))
>
>  (defun org-md-template (contents info)
>    "Return complete document string after Markdown conversion.
> --
> 2.9.2
>
>
> From 31091e4bd4b48d1394482a1542e6d90abf04b32d Mon Sep 17 00:00:00 2001
> From: Jake Romer <address@hidden>
> Date: Sun, 7 Aug 2016 16:15:50 -0400
> Subject: [PATCH 2/2] Export Table of Contents as Markdown

This commit message is also incomplete.
>
> ---
>  ox-md.el | 15 ++++++++++++++-
>  1 file changed, 14 insertions(+), 1 deletion(-)
>
> diff --git a/ox-md.el b/ox-md.el
> index 865e123..0e2a499 100644
> --- a/ox-md.el
> +++ b/ox-md.el
> @@ -528,6 +528,19 @@ INFO is a plist used as a communication channel."
>           "\n"))))))
>
>
> +;;;; Table of contents
> +
> +(defun org-md-format-toc (headline)

Ideally, this should handethe level and a scope so as to handle toc:3
or #+TOC: headlines local.

> +  "Return an appropriate table of contents entry for HEADLINE.
> +INFO is a plist used as a communication channel."
> +  (let* ((title (org-export-data (org-export-get-alt-title headline info) info))
> +         (level (1- (org-element-property :level headline)))
> +         (indent (concat (make-string (* level 2) ? )))

"? " -> "?\s"

Besides, the indentation is slightly wrong. IIRC, 4 spaces are expected
between two levels. See, e.g., `org-md-item'.

> +         (anchor (or (org-element-property :CUSTOM_ID headline)
> +                     (org-export-get-reference headline info))))
> +    (concat indent "- [" title "]" "(#" anchor ")")))
> +
> +
>  ;;;; Template
>
>  (defun org-md-inner-template (contents info)
> @@ -538,7 +551,7 @@ holding export options."
>    ;; footnotes with at least a blank line.
>    (let* ((depth (plist-get info :with-toc))
>           (headlines (and depth (org-export-collect-headlines info depth)))
> -         (toc-string (org-html-toc depth info))
> +         (toc-string (or (mapconcat 'org-md-format-toc headlines "\n") ""))

#'org-md-format-toc

>           (toc-tail (if headlines "\n\n" ""))

Maybe a better abstraction would be to let `org-md-format-toc' handle
toc-string and toc-tail.

Regards,

--
Nicolas Goaziou

render-fn-as-md.patch
Description: Binary data