We already have per-level navigation definitions and additions from tickets such as and GUISE-144.
We need to be able to specify navigation, or more importantly, add to navigation on a per-page basis. We can do it using a navigation side car in the form .filename.ext.navigation.*. The presence of the .filename.ext.navigation.* will be considered to reset the navigation for that page. Any .filename.ext.navigation+.* file will be added to the reset .filename.ext.navigation.* definition or to the existing definition.
Although there are several possible approaches, it will be simpler to consider that
Combined with existing logic, the page navigation would be considered like this:
Find base page navigation.
If the artifact is for a source file and there is a .filename.ext.navigation.* file, use that.
Otherwise search for general .navigation.* and .navigation+.* files up the hierarchy as in and GUISE-144.
If the artifact is for a source file, add the contents of any .filename.ext.navigation+.* file.
Currently the navigation calculations are being done for page source files, because at the moment we don't have any directories that serve content without a content file.
If theoretically a directory could have content, then the per-page annotation definition file would be ..navigation.* or .navigation.*, the later of which would be no different than the navigation file from et. al. This could be worked around by making the navigation filename construction more complicated, but that may not be useful.
Instead this this ticket is preventing the use of per-page navigation files if the artifact is a directory. This means that in the future if a directory ever provides its own content, it will not be possible using this mechanism to specify or add navigation just to the directory page; the .navigation.* and .navigation+.* file will apply to the entire directory as in GUISE-134. This makes a lot of sense, as the files in the directory are subordinate to the directory page.
Nevertheless per-page navigation would be able to be specified for just the directory page using the directory content file, which for the moment is the only way to provide content for a directory anyway.