Fix internal links (#19)

* Add failing test for internal links

As reported in
#18, I
ran into this with links to footnotes when using ox-html-stable-ids.

This patch adds a failing test which hopefully outlines a way to
resolve this issue. Currently, the id and hrefs remain empty, so
they're removed, resulting in broken links.

Instead, it'd be great if we could use the reference we use in the
link as the anchor. However, other options would also be acceptible,
as long as it fixes the link issue and produces stable IDs.

* Fall back to :value when no :raw-value exists

The test case for internal links passes if
org-html-stable-ids--extract-id falls back to using the element's
:value property when it has no :raw-value property.

This breaks a different test, though, which relies on the return value
being nil if :raw-value doesn't return anything. It might make sense
to only fall back to :value when the :raw-value key doesn't exist at
all.

* Only use :value when it's not deferred

Falling back to the :value property works for inline elements where
the :value is string based, like links. For block-level elements like
example blocks, which have nested elements, those elements get
automatically serialized to a string by org-element-property.

The :value fallback should only work for inline elements, so this
patch switches to using org-element-property-raw, which doesn't
serialize the "deferred" elements. To make sure that doesn't happen,
the new org-html-stable-ids--extract-value function only returns
non-deferred :value properties.

* Manually detangle changes to Org document

* Update description of ID creation, explain extracting values

Author: jeffkreeftmeijer

ox-html-stable-ids.el

@@ -33,6 +33,12 @@
   :package-version '(Org . "8.0")
   :type 'boolean)
 
+(defun org-html-stable-ids--extract-value (datum)
+  (let ((value (or (org-element-property :raw-value datum)
+                   (org-element-property-raw :value datum))))
+    (unless (org-element-deferred-p value)
+      value)))
+
 (defun org-html-stable-ids--extract-id (datum)
   "Extract a reference from a DATUM.
 
@@ -41,7 +47,7 @@ Return DATUM's `:CUSTOM_ID` if set, or generate a reference from its
 nil."
   (or
    (org-element-property :CUSTOM_ID datum)
-   (let ((value (org-element-property :raw-value datum)))
+   (let ((value (org-html-stable-ids--extract-value datum)))
      (when value
        (org-html-stable-ids--to-kebab-case value)))))
 

ox-html-stable-ids.org

@@ -72,10 +72,16 @@ It only replaces IDs in exported HTML documents when ~org-html-stable-ids~ is no
 The function that generates headlines in Org's HTML exporer (~org-html-headline~) calls a function called ~org-export-get-reference~ to generate a unique reference for the headline.
 Ox-html-stable-ids adds an advice to overrides that function to return stable IDs, based on the headline's contents, instead.[fn:adam-porter]
 
-First, the ~org-html-stable-ids--extract-id~ helper function takes a headline and returns a stable ID:
+First, the ~org-html-stable-ids--extract-id~ helper function takes an element and returns a stable ID:
 
 #+name: extract-id
 #+begin_src emacs-lisp
+  (defun org-html-stable-ids--extract-value (datum)
+    (let ((value (or (org-element-property :raw-value datum)
+                     (org-element-property-raw :value datum))))
+      (unless (org-element-deferred-p value)
+        value)))
+
   (defun org-html-stable-ids--extract-id (datum)
     "Extract a reference from a DATUM.
 
@@ -84,13 +90,14 @@ First, the ~org-html-stable-ids--extract-id~ helper function takes a headline an
   nil."
     (or
      (org-element-property :CUSTOM_ID datum)
-     (let ((value (org-element-property :raw-value datum)))
+     (let ((value (org-html-stable-ids--extract-value datum)))
        (when value
          (org-html-stable-ids--to-kebab-case value)))))
 #+end_src
 
-If the headline has a ~:CUSTOM_ID~ property, that's immediately returned.
-If not, the ID is created by taking the headline's contents and converting them to "kebab case".
+If the element has a ~:CUSTOM_ID~ property, that's immediately returned.
+If not, element's contents are used through the ~org-html-stable-ids--extract-value~ function.
+To create te ID, the value is then converted to "kebab case".
 
 #+begin_aside
 

test.el

@@ -64,3 +64,13 @@
    (let ((org-html-stable-ids t))
      (org-html-export-as-html)))
   (org-html-stable-ids-remove))
+
+(ert-deftest internal-link-test ()
+  (org-html-stable-ids-add)
+  (find-file "test/fixtures/internal-link.org")
+  (let ((org-html-stable-ids t))
+    (org-html-export-as-html))
+  (let ((buffer (with-current-buffer "*Org HTML Export*" (buffer-string))))
+    (should (string-match-p "<a id=\"first\"></a>Something" buffer))
+    (should (string-match-p "See item <a href=\"#first\">1</a>" buffer)))
+  (org-html-stable-ids-remove))

test/fixtures/internal-link.org

@@ -0,0 +1,2 @@
+1. <<first>>Something
+2. See item [[first]]