Support cross-references
vermiculus opened this issue · 26 comments
As you can see by the very ability to link to this specific heading, GitHub's HTML supports auto-linking to headings. Unfortunately, if you try a cross-reference in the linked document, the link is dead. The underlying HTML that is generated looks something like
<a>My Cross-Reference</a>rather than what (I think) the correct HTML would look like
<a href="#my-cross-reference">My Cross-Reference</a>Obviously this is a contrived example and the anchor may be different in practice.
I'm not privy to how this functionality is actually effected, so this may not be possible depending on whether these anchors are auto-generated. (Such a generator would be somewhere in github/markup though, yes?) Is this feature feasible?
Hi, sorry I was not aware of this functionality..
I see that in your document a heading contains an ID which which then you use to link to it by using a link like this: [[id:7DC6B787-4AE5-45FF-9D78-8ABE8FD3E38F][Layout Algorithms]].
*** Layout Algorithms
:PROPERTIES:
:ID: 7DC6B787-4AE5-45FF-9D78-8ABE8FD3E38F
:noweb-ref: nil
:END:
Tracking these ids then to make references to headlines should be handled by Org ruby and I got an idea on how it would be implemented.
By the way, how do you generate the ids or are they done manually?
No need to apologize! They're generated automatically; check out the variable org-id-link-to-org-use-id. Unfortunately it gets a little worse; there are a couple ways to link to things in Org. The manual is obviously the definitive resource, but here's a quick summary of what Org supports (with ones that simply don't make sense removed):
http://www.astro.uva.nl/~dominik on the web
doi:10.1000/182 DOI for an electronic resource
file:/home/dominik/images/jupiter.jpg file, absolute path
/home/dominik/images/jupiter.jpg same as above
file:papers/last.pdf file, relative path
./papers/last.pdf same as above
file:/myself@some.where:papers/last.pdf file, path on remote machine
/myself@some.where:papers/last.pdf same as above
file:projects.org another Org file
file:projects.org::some words text search in Org file
file:projects.org::*task title heading search in Org file
id:B7423F4D-2E8A-471B-8810-C40F074717E9 Link to heading by ID
news:comp.emacs Usenet link
mailto:adent@galaxy.net Mail link
As for my own use case (and what I imagine would be the among more common ones), I use the ID-based approach and an (unlisted?) variant of file:projects.org::*task title. If the file descriptor is missing, it simply links within the same file. I find the ID approach to be safest though—it's not hard to imagine a document with similarly-named headings.
I see, thanks for the explanation! I think it should be feasible to include some of this functionality.
Thanks! Let me know if there's anything I can do to help.
Bit of a neophyte here…I have problem that may be related.
There's a formatting option for "intra-links" (i.e. cross-references, I guess?) in org-mode that looks like this:
[[free vs. open source software--a controversy?][a difference?]]
which links to a location in my document that looks like this (I've included the surrounding context--it links specifically to the third line, which has the same text as the link above):
* Philosophy and thinking about software--The Why?
** where does your software come from?
*** free vs. open source software--a controversy?
Clicking on the link that is generated via the github conversion produces the following URL:
https://github.com/cicerojones/FOSS-media-arts-guide/blob/master/free%20vs.%20open%20source%20software--a%20controversy?
which, of course, gives a 404.
Does all that make sense? I don't use IDs as the above poster does; don't know if that would help. This seems straightforward enough in org-mode--I may be in over my head here on Github.
FWIW,
This is the HTML that is generated when org-mode does the org-->html conversion.
<a href="#sec-5-1-1">a difference?</a>Thanks for your help (and work--great to have this org-mode conversion in general!)
Just a "me too" request for this feature. It would be great if it could be implemented. I made a gist to illustrate the different internal link types.
I think that it would be sufficient to support just the ID and CUSTOM_ID links, which are types 1 and 3 in my gist. The other variety described by @cicerojones above have many disadvantages and would also be much trickier to implement (I imagine).
Another "me too" here. My use case: I write my .emacs config in org-mode and publish it to github, but the internal links don't work in the published version.
Elisp links do something wacky to org-ruby.
I know these aren't supposed to do anything--but instead of nothing, or a broken link, I get a lot of gnarly characters instead.
For example, this Org link "[[elisp:(switch-to-buffer "*watir*")]["watir"]]" results in the following being output to HTML: "<a href=”elisp:(switch-to-buffer “@@html:<b>@@watir@@html:</b>@@”)”>”watir”".
I have an example of this in this Gist.
This is what I see in the above link:
This would be very helpful. As it is, packages like https://github.com/alphapapa/org-make-toc have to work around this by creating GitHub/org-ruby-compatible links manually. And links made with Org itself don't work.
Just throwing in a vote. I was working on a readme formatting in with org-mode and discovered my internal links using the [[search]] and <<direct target>> formats are broken when rendered on GitHub. This would definitely be nice to have 😄
I'd also be very interested in this. This is an issue in GitLab-CE (and ostensibly the whole site), which depends on org-ruby to do its parsing to HTML. As @deprecated said, it would be good enough to support just ID and CUSTOM_ID links - org-mode's fuzzy matching is bad practice for so many reasons.
I'm also going to take a throw at this, because I really need anchor parsing - at least to HTML - to work for my Gitlab instance.
A surface-level search suggests that GitLab (https://gitlab.com/gitlab-org/gitlab-markup) and GitHub (https://github.com/github/markup) should be adding anchors after org-ruby is done. The process involves a lot of sanitization due to the sensitive nature of rendering arbitrary HTML. This does not necessarily explain why GitLab does not provide anchor links next to headers in rendered org-flies, but it suggests that both parsers may be friendly to header links that org-ruby hands to them.
I looked into it and can confirm that the GitLab/Hub parsers (which come after org-ruby) will always overwrite id attributes for the headings. The obvious workaround to actually setting the ids - put elements next to the headers with the respective CUSTOM_ID and ID properties as their HTML ids - will also fail because those appear to get scrubbed.
See this repo for more information about this rendering process.
This can still probably be implemented, though; the standard id attribute seems to be made of the header, lower-cased and dash-delimited, so all we really have to do is guess what the header's HTML id will look like and set the href to point to that id. I personally think that's malarkey, but it should work for the most important uses (on GitHub/Lab).
As @deprecated said, it would be good enough to support just ID and CUSTOM_ID links - org-mode's fuzzy matching is bad practice for so many reasons.
That would not be good enough, because it would require that headings have manually assigned ID or CUSTOM_ID properties, which is already required to produce links that are followable in both Org and org-ruby-generated HTML. In other words, that is already the case.
What is needed is support for Org's own intra-file heading links. They are described in the Org manual, in section 4.7 Search options in file links:
Here is the syntax of the different ways to attach a search to a file
link, together with an explanation:
[[file:~/code/main.c::255]]
[[file:~/xx.org::My Target]]
[[file:~/xx.org::*My Target]]
[[file:~/xx.org::#my-custom-id]]
[[file:~/xx.org::/regexp/]]
`255'
Jump to line 255.
`My Target'
Search for a link target `<<My Target>>', or do a text search for
`my target', similar to the search in internal links, see *note
Internal links::. In HTML export (*note HTML export::), such a
file link will become an HTML reference to the corresponding named
anchor in the linked file.
`*My Target'
In an Org file, restrict search to headlines.
`#my-custom-id'
Link to a heading with a `CUSTOM_ID' property
`/regexp/'
Do a regular expression search for `regexp'. This uses the Emacs
command `occur' to list all matches in a separate window. If the
target file is in Org mode, `org-occur' is used to create a sparse
tree with the matches.
As a degenerate case, a file link with an empty file name can be used
to search the current file. For example, `[[file:::find me]]' does a
search for `find me' in the current file, just as `[[find me]]' would.
Specifically, what's needed is support for these:
For intra-file links, this format:
`*My Target'
In an Org file, restrict search to headlines.
Which should be simply expanded to, e.g.:
<a href="#My%20Target">My Target</a>For inter-file links, this format:
[[file:xx.org::*My Target]]
Which should be simply expanded to, e.g.:
<a href="xx.org#My%20Target">My Target</a>Where xx.org is a file in the same directory.
the standard
idattribute seems to be made of the header, lower-cased and dash-delimited, so all we really have to do is guess what the header's HTMLidwill look like and set the href to point to thatid. I personally think that's malarkey, but it should work for the most important uses (on GitHub/Lab).
Yes, this is the workaround we have to do in org-make-toc and toc-org. And the problem is that it creates links like [[#heading-name]] which Org interprets as links to headings with CUSTOM_ID properties, so Org can't follow those links unless the user manually assigns such custom IDs to each heading.
toc-org provides a hack that uses org-link-translation-function to parse #heading-name-style links specially, which breaks compatibility with Org documents that aren't intended to be rendered by GitHub.
It's very frustrating that it's not possible to create links that work both within Org and as rendered by GitHub!
I don't think manually-assigned ID or CUSTOM_ID properties aren't worth implementing – even as a separate stepping stone to full support of Org links. The latter may be much harder to do. Making it possible to create working intra-document links is worth the inconvenience of additional properties tucked away in a drawer. (That said, it's good to note to design the enhancement in such a way that does not close the door on inter-document links.)
@vermiculus Do you mean implementing a command in Emacs to add such ID properties to an Org document automatically, or do you mean something in org-ruby?
Org can already assign IDs to headlines you link to with C-c C-l. It'll generate a GUID to use.
I wouldn't expect org-ruby to make any modifications to the document (ever) nor do any parsing of its generalized link syntax (yet).
Yes, I meant implementing a command to assign IDs to all headings in a document so they could be linked in a table of contents.
A generated table of contents is a slightly different request; I'd recommend opening a new issue and marking this one as related. (This is specifically about cross-references created 'manually' (i.e., with a command) that are saved in the documented as committed to git.)
@vermiculus I'm not talking about org-ruby generating a table of contents. I'm talking about the tables of contents generated by org-make-toc and toc-org, which generate the ToCs in Emacs using the links and cross references discussed in this issue. Please see my earlier comments about the problems with such and how org-ruby could be changed to fix them.
My apologies; I'd been skimming for the phrase 'table of contents', not 'toc' :-) If a table of contents exists literally in an Org document, then of course having that TOC work would be in-scope.
Just want to echo that it would be extremely useful to have internal links that work both in org-mode and on GitHub.
This feature will be super useful to those that keep an org-roam (zettelkasten) repo in github. Many of my links are handled by org-id and github cannot parse them at all.
For example I handle my files like this
:PROPERTIES:
:ID: 20200701060753
:END:
#+TITLE: My note
And link them like this
[[id:20200701060753][My note]]
Adding a vote on this issue.