ox-md: Export links to equations for use with MathJax

ox-md: Export links to equations for use with MathJax

[Thibault Marin]

[-- Attachment #1: Type: text/plain, Size: 588 bytes --]


Hi list,

Similar to a change introduced recently to ox-html (ba6c0f1ea9), I'd
like to be able to export (in markdown, using ox-md.el) links to LaTeX
equations with "\eqref{org0000000}" and rely on MathJax for rendering
instead of the default markdown format ("[description][#org0000000]").

The attached patch is my first attempt at this.  It is almost identical
to the ox-html version.  I have added an option to select which mode to
use (markdown or MathJax).

Could this patch be considered for a merge?  Please let know if there
are any suggestions or comments.

Thanks,

thibault


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-md.el-Add-option-to-export-equation-links-to-eqre.patch --]
[-- Type: text/x-diff, Size: 3647 bytes --]

From bf03749fe18726f43684d0818a75a2affbe3e546 Mon Sep 17 00:00:00 2001
From: thibault <thibault.marin@gmx.com>
Date: Sat, 10 Feb 2018 22:58:35 -0600
Subject: [PATCH] ox-md.el: Add option to export equation links to "\eqref"
 (MathJax)

* lisp/ox-md.el (org-md-link): Export link to LateX equation as
"\eqref" (for use with MathJax) when the new option `:md-link-mathjax'
is non-nil.
(org-export-define-derived-backend 'md): Add new option
`:md-link-mathjax' to control the export of equation links.  Its value
is set to that of the new customization variable `org-md-link-mathjax'.
(org-md-link-mathjax): Add customization variable to enable export to
MathJax "\eqref" (disabled by default).
---
 lisp/ox-md.el | 45 +++++++++++++++++++++++++++++++++------------
 1 file changed, 33 insertions(+), 12 deletions(-)

diff --git a/lisp/ox-md.el b/lisp/ox-md.el
index e2a000bd0..575499072 100644
--- a/lisp/ox-md.el
+++ b/lisp/ox-md.el
@@ -70,6 +70,17 @@ The %s will be replaced by the footnote reference itself."
   :version "26.1"
   :package-version '(Org . "9.0"))
 
+;;;; Links
+
+(defcustom org-md-link-mathjax nil
+  "Non-nil means process LaTeX equation links for MathJax.
+
+When non-nil, links to LaTeX equations will be exported to \"\\eqref\"."
+
+  :group 'org-export-md
+  :package-version '(Org . "9.2")
+  :type 'boolean)
+
 \f
 ;;; Define Back-End
 
@@ -111,7 +122,8 @@ The %s will be replaced by the footnote reference itself."
   :options-alist
   '((:md-footnote-format nil nil org-md-footnote-format)
     (:md-footnotes-section nil nil org-md-footnotes-section)
-    (:md-headline-style nil nil org-md-headline-style)))
+    (:md-headline-style nil nil org-md-headline-style)
+    (:md-link-mathjax nil nil org-md-link-mathjax)))
 
 \f
 ;;; Filters
@@ -419,17 +431,26 @@ a communication channel."
 	    (or (org-element-property :CUSTOM_ID destination)
 		(org-export-get-reference destination info))))
 	  (_
-	   (let ((description
-		  (or (org-string-nw-p contents)
-		      (let ((number (org-export-get-ordinal destination info)))
-			(cond
-			 ((not number) nil)
-			 ((atom number) (number-to-string number))
-			 (t (mapconcat #'number-to-string number ".")))))))
-	     (when description
-	       (format "[%s](#%s)"
-		       description
-		       (org-export-get-reference destination info))))))))
+           (if (and destination
+                    (plist-get info :md-link-mathjax)
+                    (eq 'latex-environment (org-element-type destination))
+                    (eq 'math (org-latex--environment-type destination)))
+               ;; Caption and labels are introduced within LaTeX
+               ;; environment.  Use "eqref" macro to refer to those in
+               ;; the document.
+               (format "\\eqref{%s}"
+                       (org-export-get-reference destination info))
+             (let ((description
+                    (or (org-string-nw-p contents)
+                        (let ((number (org-export-get-ordinal destination info)))
+                          (cond
+                           ((not number) nil)
+                           ((atom number) (number-to-string number))
+                           (t (mapconcat #'number-to-string number ".")))))))
+               (when description
+                 (format "[%s](#%s)"
+                         description
+                         (org-export-get-reference destination info)))))))))
      ((org-export-inline-image-p link org-html-inline-image-rules)
       (let ((path (let ((raw-path (org-element-property :path link)))
 		    (cond ((not (equal "file" type)) (concat type ":" raw-path))
-- 
2.15.1

Re: ox-md: Export links to equations for use with MathJax

[Nicolas Goaziou]

Hello,

Thibault Marin <thibault.marin@gmx.com> writes:

> The attached patch is my first attempt at this.  It is almost identical
> to the ox-html version.  I have added an option to select which mode to
> use (markdown or MathJax).

Thank you.

> Could this patch be considered for a merge?  Please let know if there
> are any suggestions or comments.

Markdown has no direct business with Mathjax, so introducing Mathjax
components in "ox-md.el" sounds wrong to me. "ox-md.el" doesn't even
have any math-related function (it lets "ox-html.el" take care of LaTeX
fragments and environments).

Since it is a specific requirement, you may want to define your own
Markdown back-end in this case (e.g., replacing `org-md-link' with
`org-html-link' in some cases).

Another option would be to introduce a boolean variable like
"org-md-internal-links-as-html", but I'm not sure it would be generally
useful.

WDYT?

Regards,

-- 
Nicolas Goaziou

Re: ox-md: Export links to equations for use with MathJax

[Thibault Marin]

> Markdown has no direct business with Mathjax, so introducing Mathjax
> components in "ox-md.el" sounds wrong to me. "ox-md.el" doesn't even
> have any math-related function (it lets "ox-html.el" take care of LaTeX
> fragments and environments).
OK.

> Since it is a specific requirement, you may want to define your own
> Markdown back-end in this case (e.g., replacing `org-md-link' with
> `org-html-link' in some cases).

Thanks.  The following seems to work for my need:

,----
| (defun org-ipynb-link (link desc info)
|   (let* ((type (org-element-property :type link))
|            (destination (if (string= type "fuzzy")
|                             (org-export-resolve-fuzzy-link link info))))
|       (if (and destination
|                (eq 'latex-environment (org-element-type destination))
|                (eq 'math (org-latex--environment-type destination)))
|           (org-html-link link desc info)
|         (org-md-link link desc info))))
`----

Thanks for the help.

thibault