Currently, Diviner links are generated using a title search. If we want the ability to change articles without breaking links, we should add a @link keyword. It would be a one-to-many relationship, one diviner book would allow for multiple links.
@title Internationalization @group developer @link internationalization @link i18n
A few thoughts. This sounds like a great idea as searching by article title seems a little fragile as you mention. I think a good practice for using the proposed @link would be to fully namespace it somehow like @link development.processes.i18n, though I'm not totally sure what that looks like as I'm not familiar with the Diviner format or structure. If we have the use of namespaces then managing multiple @link declarations might lead to confusion or tedious to maintain. To me this also feels more similar to something like an @id rather than @link. What are your thoughts?
Thanks for your comments! Namespacing might be useful, we would have to figure out what that looked like. I was thinking "/book/group/link" as that would be pretty natural (and is very close to what Diviner does already: "/book/group/filename"). It would also allow for us to eventually make Diviner widely useful, see secure: T4558. However, that is a broader discussion that should probably wait...
The reason that I proposed multiple links was to avoid breaking old ones. In my example above, I had the article at "i18n" then we moved it to "internationalization" - the top @link would be the primary link used in paths, the others would be redirects to the primary link. If we needed to move the article somewhere else, we'd add another @link at the top like so:
@title Internationalization @group developer @link where-the-words-go @link internationalization @link i18n
Taking the best from the two: what about assuming a default @link /book/group/best-document-ever-about-link - but still allowing custom @link to allow easy migrations?