Links between Asciidoc pages in Pelican
How to do it properly
To link to other pages in Pelican, you can use the filename thing.[1]
The link itself must be built using the syntax of the language you use to write the page. So, in the case of Asciidoc, we have the syntax for a link between documents[2], which is:
xref:{filename}theotherpage.asciidoc[Here is the other page]
When the Asciidoc is processed, Pelican replaces this with the proper link in the target format, which in our case is of course HTML:
<a href="/pages/theotherpage.html">Here is the other page</a>
For more about this, see https://docs.getpelican.com/en/3.6.2/content.html, section Linking to interal content.
My first solution
Before I knew about {filename}, I used the following solution, which works,
but is a bit ugly because we have to use the title of the document as part of
the link, which may differ from the filename.
Nevertheless, I document it here for historical reasons. Sometimes the path to the truth is long and twisted. So, a while ago I said:
Links between documents work in Pelican, if you consider some points. So far I only tried this for static pages, but it should also be possible to link to a blog entry using this method. Here’s an example of such a link:
<<pages/was-ich-kann.asciidoc#was_ich_kann, Was ich kann>>
This links to a section are marked as follows:
= Was ich kann [[was_ich_kann]]
You can omit the link after the hash, which points to a specific place (typically a section) in a document. Note that you still have to have a hash after the document name. Then the link goes to the whole document, like so:
<<pages/was-ich-kann.asciidoc#, Was ich kann>>
Of course you can now omit the link target (the one included in [[…]]) in
the document that you are linking to.
Some points to note here:
-
You have to prefix the file with pages because that’s the directory where the static pages live.
-
The filename is not the name you gave to the file (which is wasichkann.asciidoc in this case). Instead it links to the file name as constructed by Pelican (which obviously uses the text of the title and composes the output filename from that).