Broken links in some .org files

[xfq]

The TOC links in the following files are broken (404):

• https://github.com/syl20bnr/spacemacs/blob/master/doc/DOCUMENTATION.org
• https://github.com/syl20bnr/spacemacs/blob/master/doc/FAQ.org
• https://github.com/syl20bnr/spacemacs/blob/master/doc/CONVENTIONS.org
• https://github.com/syl20bnr/spacemacs/blob/master/doc/LAYERS.org
• https://github.com/syl20bnr/spacemacs/blob/master/doc/QUICK_START.org
• https://github.com/syl20bnr/spacemacs/blob/master/doc/VIMUSERS.org
• https://github.com/syl20bnr/spacemacs/blob/master/layers/LAYERS.org
• layers/**/README.org (I haven't tried all of them)

I think the broken links were introduced in 13c5b1d (Nov 2, 2015).

PS: the TOC links in https://github.com/syl20bnr/spacemacs/blob/master/CONTRIBUTING.org are not broken.

---

Update: Not only TOC links, but most (if not all) internal links.

[syl20bnr]

This is a known issue and we have yet to find a solution for this.

[TheBB]

I thought we landed on wontfix for this, and to have http://spacemacs.org be the "official" way to view documentation online.

[StreakyCobra]

I thought we landed on wontfix for this, and to have http://spacemacs.org be the "official" way to view documentation online.

We landed on this yes, but imho this is not a viable long-term solution. Search engines are indexing those pages, some users read the documentation on github, some users use the github search box to find information in the project, etc.

[robbyoconnor]

Add the wont fix label :D

[StreakyCobra]

Nah, we need a better solution. Discussing with @TheBB recently we were seeing a potential solution to have links working everywhere, but we are both kind of busy those days.

[louwers]

Add a custom id to every header and link to those like so:

* Spacemacs documentation                                   :TOC_4_org:noexport:
 - [[#core-pillars][Core Pillars]]
   - [[#mnemonic][Mnemonic]]
   - [[#discoverable][Discoverable]]
   - [[#consistent][Consistent]]
   - [[#crowd-configured][Crowd-Configured]]
 - [[#highlighted-feature][Highlighted feature]]
 - [[#screenshots][Screenshots]]
 - [[#who-can-benefit-from-this][Who can benefit from this?]]

Then it works from org-mode (export) and on GitHub.

It is not optimal I have to admit.

[TheBB]

Yeah, those drawers become an eyesore when reading from within Emacs.

[louwers]

By the way, if you want people to read the documentation on http://spacemacs.org you could at least link to that from the README.

[xfq]

@louwers I submitted a PR (#4737) for that just now.

[JAremko]

Came across this issues. Absolutely had to use my favorite Emacs feature #4811

[TheBB]

Never mind exporting. I can't even find a way to make a link to a heading in another file work well across github and Emacs.

I really, really, really don't want to spend my time working on this. Are we so sure this is a blocker? I can't see any solutions that are not going to be very flimsy.

[TheBB]

And no, I'm pretty sure the links we had that pointed to specific headings in other files were already broken in the previous versions.

[JAremko]

So this is my plan how to fix it:

• Try stupid stuff
• Try even more stupid stuff
• Understand that the stupid stuff is stupid and try to come up with something less stupid
• Come up with a bold plan:
  Instead of trying to shoehorn some kind of insanity into the org files or Spacemacs to make .org stuff almost work both on GitHub and in the Spacemacs - with all kind of ugliness like # everywhere or broken links here and there - we can simply fix the org files for GitHub when they are on GitHub and for Spacemacs when they are in Spacemacs! With all kind of benefits.
  TODO:
  • Make a function for formatting org files for GitHub [WIP]add function that formats org files for GitHub #5342
  • Make a function for formatting org files for Spacemacs i.e. make them normal org files. And hook it up to the layer install process. [WIP] Function for formatting githubified org files for Spacemacs #5345 (WIP)
  • Add Travis test to make sure that PR's README.org files are properly formatted and will look normal on GitHub.
  • Add Contrib-layer that will help in creating new layers, testing them, formatting, and creating PR that follows the guidelines. bonus level!

@syl20bnr I need a feedback before I spent all of my free time on this 😄

[a13ph]

Or to toc-org, if that's the issue 😮

[JAremko]

@a13ph Well. GitHub can't allow all kind of symbols in URLs so the fix will be some kind of band-Aid in js that will probably move it too far away from how markdown works. Or they will have to sanitize TOC on their end i.e. changing user's content. It will be too much hassle and will take ages to push trough. Or it will be simply rejected because it's up to users to submit properly formatted content.

[JAremko]

Also the solution for handling links in Spacmacs relies on some specific stuff like that the local files will start with https://github.com/syl20bnr/spacemacs/ and then we can rewrite them (or redirect via hooks) to the local copies and open them in the org mode.

[a13ph]

I'm unsure, but isn't this relevant? snosov1/toc-org#3

[a13ph]

Those hooks and specific stuff - it's an ugly hack, IMO. If it can be done cleanly - fine.

But i'm not sure we are the only ones with this issue and it wouldn't hurt to ask those who are responsible even if we do pursue workarounds.

Kinda strange not even opening an issue, considering where we are and who this issue is with.

[JAremko]

Kinda strange not even opening an issue, considering where we are and who this issue is with.

I'm not sure if GitHub has an issue(nor that it's not opened 😄 ). links like #foo/bar are working. And you can use them to link other documents. Sure it doesn't provide all of org utilities like text links with a search and stuff, but it is the cost of being in the web environment. It will be hard to make them do something about it.

Those hooks and specific stuff - it's an ugly hack, IMO. If it can be done cleanly - fine.

I also think that it's a bit meh. We probably could handle it without the magic by simply formatting(removing github fixes and making links local) org files when they are opened. But we can go with toc-org if syl20bnr says so.

I need to write some tests and dig into the link magic.

[JAremko]

Created a pull request snosov1/toc-org/pull/13 it should make toc-org more reliable(or, knowing me, somehow in someway broken 😄 )

[JAremko]

I'm halfway there. It will be epic PR. I only hope not too epic 😄

Also I have found a surprisingly reasonably way to make it all work with the site.

So far it looks like we can fix all the links. Even links to headings in different files.

[a13ph]

@JAremko thanks, I think this will make reading docs much more tolerable [at least for me!] if all links work (less mental load than jumping or searching through whole file)

[JAremko]

Looks like tomorrow is the day

[JAremko]

Here it is... #5545

[d12frosted]

Fixed with released of Spacemacs v0.200. Let us know if you still have any problems with this issue.

[alphapapa]

FYI, if this is still relevant, you may find this useful in generating tables of contents more flexibly: https://github.com/alphapapa/org-make-toc