* Meaningful & stable anchors in HTML export
@ 2016-07-01 10:46 Vladimir Alexiev
2016-07-01 12:22 ` Nicolas Goaziou
0 siblings, 1 reply; 2+ messages in thread
From: Vladimir Alexiev @ 2016-07-01 10:46 UTC (permalink / raw)
To: emacs-orgmode
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"
^ permalink raw reply [flat|nested] 2+ messages in thread
* Re: Meaningful & stable anchors in HTML export
2016-07-01 10:46 Meaningful & stable anchors in HTML export Vladimir Alexiev
@ 2016-07-01 12:22 ` Nicolas Goaziou
0 siblings, 0 replies; 2+ messages in thread
From: Nicolas Goaziou @ 2016-07-01 12:22 UTC (permalink / raw)
To: Vladimir Alexiev; +Cc: emacs-orgmode
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
^ permalink raw reply [flat|nested] 2+ messages in thread
end of thread, other threads:[~2016-07-01 12:22 UTC | newest]
Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2016-07-01 10:46 Meaningful & stable anchors in HTML export Vladimir Alexiev
2016-07-01 12:22 ` Nicolas Goaziou
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).