Background

While creating a bibliography using nikola I found about nikola path handlers. It allows you to make reference to other posts without needing the full address (e.g. http://necromuralist.github.io/pages/nikola-inter-site-links).

Instead you can use the special link:// protocol and nikola will resolve it for you. It uses the form:

link://<kind>/<name>/

There is (of course) another form that lets you doc it using the :doc: restructured text directive. This form is more succinct, and is what I'll probably stick with in the future. I originally went with the link version because I thought it would work with other markup languages, but it didn't (or at least not with org-mode).

Post-Paths

In this case I'm trying to link to another post so the link kind is post_path, which will resolve to either posts or pages. Because it can be either one, you need to extend the path to this form:

link://post_path/posts/<post-slug>/

Example

Here's how to link to another post that I titled Pruning Large Files From Git with BFG, with a slug of pruning-large-files-from-git-with-bfg.

`link <link://post_path/posts/pruning-large-files-from-git-with-bfg/>`__

This creates this link.

Doc Role

This is a restructured-text role that nikola supports to make it easier to install links. The previous example using this style would be done like this:

:doc:`link <pruning-large-files-from-git-with-bfg>`

Which creates this link.

Conclusion

The doc method seems much easier for posts, but the links method covers many other cases and might be useful otherwise. It should be noted that both methods work for pages as well (stories), although the link version will need the path changed. In my case, all the pages are under the stories folder so the link would be change to something like:

`link <link://post_path/stories/story-slug/>`__