I’d like to have a table of contents in the README file for my project. I have a README file in the root directory of the project and PlDoc reads it and renders it fine.
My code is hosted on Github so I added a ToC using Github conventions. The Github markdown parser automatically adds anchor tags to all headers in a README. So it’s possible to make a ToC using labelled markdown links, as follows:
[Introduction](#introduction)
That can then be used to jump to the Introduction header because, on Github, the Introduction header html gets an anchor tag like: <a name="introduction"/>.
But of course, this does not work with PlDoc. So I tried to create local links using PlDoc markdown. I can’t figure out how to do it. I tried the following
First of all you need to give the section a label. They have no label by default. You do that using, e.g.,
## Introduction {#intro}
Next, you need a link. That can be done using the construct below. Using angle brackets relaxes the test for a valid hyperlink. As this is not ambiguous anyway in the [Title](#label) case I’ve pushed a patch to PlDoc to allow for simply [Title](#label). You need to upgrade to the git version though.
Thank you Jan, that’s fantastic. Lightning fast, as usual.
I’ll check out the new patch. It’s been a while since I built Swi from sources- I think I shouldn’t try it on windows, but there’s the WSL, I’ll try with that.
Unfortuantely it seems that, while the PlDoc syntax you suggested works, it is messed up by the Github markdown parser.
Note I haven’t tried the latest git version yet- I was trying things out with the old angle-bracket link syntax on the github editor. The Github markdown parser treats the manually given label in a rather unexpected manner. It seems to parse the label correctly, so it creates an anchor for it but it also automatically creates its own label for each header… and concatenates it to the manually given label.
So if I create a label #introduction in my README I end up with an anchor named #introduction-introduction on Github.
On that page, the first link in the ToC is to the header titled “What Louise, is” and it has a link to (#what-louise-is). The link doesn’t work. If you go to the named header and hover your mouse to the left of the header text a link icon appears and you can see a reference to #what-louise-is-what-louise-is.
In the meantime, the PlDoc links work fine so I can have my ToC in PlDoc.
It looks like I’ll have to maintain two separate README files and find a way to convince PlDoc and Github to read the right one. Which may not be possible.
Eh, I’ll think of something. Thank you again Jan- obviously this is a Github issue.
The aim is to be able to write reasonable pages that will look ok on both Github and PlDoc. This is a bit of a problem I guess though. Their may be a point in automatic generation of a anchor from a header text. There is also a point in be able to set this explicitly to keep URLs stable and short. If we go for the automatic thing and want to show on Github we should exactly replicate their algorithm to compute the anchor, no?
The ideal way out is probably to add automatic anchors to PlDoc. Anyone has a pointer to Github’s algorithm? Second great thing would be that if the anchor is specified, Github will simply respect that. That is not in our hands though
The aim is to be able to write reasonable pages that will look ok on both Github and PlDoc.
Well… I could just avoid having a ToC in the first place, since that’s what’s causing all the trouble.
The only reason I have a ToC is that my README is too long to navigate easily without a ToC. But that’s only by accident. My original plan was to keep the README short, as a very quick introduction to the project, and put the full details in a pdf manual. Only, there’s so much stuff to put in the manual that I keep postponing writing it. In the meantime, the README is the de-facto manual and it grows and grows to the point where I kind of need a ToC to make it easy to read
The ideal way out is probably to add automatic anchors to PlDoc. Anyone has a pointer to Github’s algorithm? Second great thing would be that if the anchor is specified, Github will simply respect that. That is not in our hands though
You shouldn’t have to design your software around Github’s idiosyncracies and like you say there’s nothing you can do about how their stuff works.
Unfortunately I have no idea what Github’s algorithm for is. It may be their code is open source but it might take a bit of digging. Maybe someone else has an idea?
I could have a look to see if I can open an issue, if I can figure out what the project is for the Github markdown parser (if that is even a separate project).
