emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: "Vladimir Alexiev" <vladimir.alexiev@ontotext.com>
To: emacs-orgmode@gnu.org
Subject: Meaningful & stable anchors in HTML export
Date: Fri, 1 Jul 2016 13:46:06 +0300	[thread overview]
Message-ID: <020501d1d385$c59432b0$50bc9810$@ontotext.com> (raw)

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"

             reply	other threads:[~2016-07-01 10:46 UTC|newest]

Thread overview: 2+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2016-07-01 10:46 Vladimir Alexiev [this message]
2016-07-01 12:22 ` Meaningful & stable anchors in HTML export Nicolas Goaziou

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='020501d1d385$c59432b0$50bc9810$@ontotext.com' \
    --to=vladimir.alexiev@ontotext.com \
    --cc=emacs-orgmode@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
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).