CODEWITHSUNDEEP
htmlemacsorg-mode
brgil
brgil

Reputation: 33

Unexpected link behavior after exporting Org-mode file to HTML

I am running Org-mode 8.2.6 in Emacs 24.3.1 on Windows 7 Ultimate and have encountered a peculiarity with how links work in HTML exported from Org-mode. I have used org-id extensively to assign unique IDs to headings in Org-mode files (stored in the :PROPERTIES: drawer of the heading).

Before the new exporter framework was introduced in Org-mode 8.0 all of these links worked without issue. No matter the level of the heading's hierarchy, exported-HTML ID-based links worked fine. However, using the new exporter framework produces different results. Now, ID-based links always fail when the target heading lies at a level below the headline level defined in the export settings, which defaults to level 3 (H:3). Note: This is true only for the exported HTML; ID-based links work perfectly within Emacs.

Here is a minimal example that demonstrates this behavior when I export it to HTML (see annotations for details):

* Headline Level 1
** Headline Level 2
*** Headline Level 3
:PROPERTIES:
:ID:       307db49e-e001-4a7b-9541-96eee2ae6f06
:END:
**** <<heading-level-4>>Non-headline level
:PROPERTIES:
:ID:       3be9179d-f838-4052-93ca-6c76c9aff12d
:END:
** Headline Level 2
*** Headline Level 3
Now I want to link to information that appears elsewhere in the file. Links work as 
expected within Emacs. When exported to HTML, however, links do not work as they 
did before the new exporter framework was introduced in Org-mode 8.0.
**** ID-based link: [[id:307db49e-e001-4a7b-9541-96eee2ae6f06][Headline Level 3]]
This link /does/ work. Using IDs always works for links to any headline level. By 
"headline level" I mean any Org-mode heading that is defined as a headline 
(default H:3).
**** ID-based link: [[id:3be9179d-f838-4052-93ca-6c76c9aff12d][Non-headline level]]
This link using the ID /doesn't/ work when exported to HTML using the new exporter 
framework. Now, using IDs as the target for links /always/ fails for links to any 
headline lower than the headline level defined in the export settings.
**** Non-ID-based link: [[heading-level-4][Non-headline level]]
Using an internal link works, but I have /many/ existing files that depend on IDs 
for links at heading levels lower than the levels I want treated as (numbered) 
headlines, and I also sometimes link to targets in other files, in which case, 
using ID's creates a much simpler workflow.

If the file above is named demo-links.org the default output file is demo-links.html. The HTML for the target of the first working link looks like this:

<h4 id="sec-1-1-1"><a id="ID-307db49e-e001-4a7b-9541-96eee2ae6f06" name="ID-307db49e-e001-4a7b-9541-96eee2ae6f06"></a><span class="section-number-4">1.1.1</span> Headline Level 3</h4>

and the HTML for the link to it looks like this:

<a href="#sec-1-1-1">Headline Level 3</a>

The link ID is part of the target code but isn't used in the linking code.

The HTML for the target of the non-working link looks like this:

<ul class="org-ul"><li><a id="heading-level-4" name="heading-level-4"></a>Non-headline level<br /><div class="outline-text-5" id="text-1-1-1-1"></div></li></ul>

Notice that the code that is generated does NOT contain the ID (3be9179d-f838-4052-93ca-6c76c9aff12d). Neither does it contain a section ID like the previous link did.

The HTML for the link to it looks like this:

<a href="#sec-1-1-1-1">Non-headline level</a>

I believe the relevant code in ox-html.el appears following the comment "Links pointing to a headline" but I'm a novice (at best) with elisp.

My question is this: Is this behavior by design, or is there some setting I can alter that will make the export work the way it did before the new export framework was introduced?

Upvotes: 3

Views: 872

Answers (2)

kuangdash
kuangdash

Reputation: 37

I encounter the problem too. What's more, text enclosed between "<<" and ">>" can be showed in the exported HTML in org-7.9 while it can't be showed in org-8.2

With limited reputations, I can't vote the item up, so I just answer it without a correct answer here. (=_=)

Upvotes: 1

Sigma
Sigma

Reputation: 1003

Looking at the code of the org-html-headline function, it seems that the "standard headline" case (whatever is exported to hN) is handling the custom IDs specially:

(let* (...
       (ids (remove nil
                    (list (org-element-property :CUSTOM_ID headline)
                          (concat "sec-" section-number)
                          (org-element-property :ID headline))))
       (preferred-id (car ids)) ;; <- here, id for the header is sec-XXX
       (extra-ids (cdr ids))
       ...)
  (format ...
          (format "outline-container-%s"
                  (or (org-element-property :CUSTOM_ID headline)
                      (concat "sec-" section-number)))
          ...
          (format "\n<h%d id=\"%s\">%s%s</h%d>\n"
                  level1
                  preferred-id
                  (mapconcat
                   (lambda (x)
                     (let ((id (org-export-solidify-link-text
                                (if (org-uuidgen-p x) (concat "ID-" x)
                                  x))))
                       (org-html--anchor id))) ;; <- generate a list of <a id=ID-XXX></a>
                   extra-ids "")
                  full-text
                  level1)
          ...))

That's where those <a id="ID-XXX" name="ID-XXX"></a> snippets come from (placeholder anchor, just to expose an additional ID)

Unfortunately, in the case of headlines that translate into list items, there is no such handling of ID/CUSTOM_ID, which quite frankly looks like a bug to me. So while it is possible to rewrite org-html-headline to do the same treatment for list items, it's unfortunately not as easy as modifying a setting (and code modification would pretty fragile)

I would suggest opening a bug report, after all it seems to be a regression.

Upvotes: 0

Related Questions