Meaningful & stable anchors in HTML export

Meaningful & stable anchors in HTML export

[Vladimir Alexiev]

Consider e.g. http://vladimiralexiev.github.io/Multisensor/#sec-3-2-2, which
uses an anchor made from the section number.
I much prefer a readable/meaningful anchor like github does:
https://github.com/VladimirAlexiev/VladimirAlexiev.github.io/tree/master/Mul
tisensor#322-normalization-problems 
Numbered anchors are bad because they are not stable: if I move the section,
the anchor will change. 

Github makes anchors from the heading text, which in my experience are a lot
more stable.
In the above case it added the section number since I have
    #+OPTIONS: num:t
in
https://raw.githubusercontent.com/VladimirAlexiev/VladimirAlexiev.github.io/
master/Multisensor/index.org.
But I'm willing to give up section numbering in favor of stable anchors.

In the HTML exporter (ox-html.el) version org-plus-contrib-20150803, the
following are tried in succession to obtain a preferred-id:

              (list (org-element-property :CUSTOM_ID headline)
                (concat "sec-" section-number)
                (org-element-property :ID headline))))

The first is manually set CUSTOM_ID property, the second a numbered secton
(eg "sec-3-2-2") and the third an ID that's automatically inserted by
org-store-link.

The newest ox-html.el
(http://orgmode.org/w/?p=org-mode.git;a=blob_plain;f=lisp/ox-html.el;hb=HEAD
) uses this

                      (list (org-element-property :CUSTOM_ID headline)
                            (org-export-get-reference headline info)
                            (org-element-property :ID headline))))

You see the second line is changed. It uses org-export-get-reference from
ox.el, 
which uses org-export-new-reference, which "Generates random 7 digits
hexadecimal numbers". 
I don't know if that is stored (which would make it stable), but it's
certainly not meaningful to any reader of the HTML file.

So my request is: the HTML export should have an option 
  org-export-anchors-use-title
to generate section anchors from the section title.

--

There is some code https://github.com/snosov1/toc-org that embeds a TOC
inside the org file,
which is very useful in github (github preview itself doesn't show a TOC).
toc-org generates meaningful (Github-like) links when
toc-org-hrefify-default is "gh".

But as described in https://github.com/snosov1/toc-org/issues/29,
Github keeps the section number, and doesn't strip the TODO and
statistics-cookies.
So a section headline like "3.2.2 TODO Normalization Problems [3/4]"
will get this anchor #322-todo-normalization-problems-34.

So it's best to include further options about which parts of a headline to
use:

- org-export-anchors-use-section-numbers
  "If org-export-with-section-numbers is also enabled, prepend the section
number (without any dashes).
This makes your anchors ugly and less stable, but you need to set this for
Github preview compatibility"
- org-export-anchors-use-todo
  "Prepend TODO/DONE keywords, in lowercase, to section anchors.
This makes your anchors ugly and less stable, but you need to set this for
Github preview compatibility"
-  org-export-anchors-use-title
  "Make section anchors from the words in the section title, converting to
lowercase and replacing punctuation with dash. 
This makes your anchors stable (title changes less frequently than
numbering) and readable. Set this for Github preview compatibility"
- org-export-anchors-use-statistics-cookies
  "Append statistic cookies (e.g. [33%] or [1/3]) to section anchor,
replacing punctuation with dash.
This makes your anchors ugly and less stable, but you need to set this for
Github preview compatibility"

Re: Meaningful & stable anchors in HTML export

[Nicolas Goaziou]

Hello,

"Vladimir Alexiev" <vladimir.alexiev@ontotext.com> writes:

> So my request is: the HTML export should have an option 
>   org-export-anchors-use-title
> to generate section anchors from the section title.

I disagree. Using headline is brittle since it is relatively common for
some headlines to share the same title, and Org internal anchor
mechanism should guarantee there are no duplicates.

You can use a CUSTOM_ID property to force the name of the section
anchor.

Regards,

-- 
Nicolas Goaziou