Add metadata to help identify nav report false positives
Problem
In the current monthly chores, the task to look for missing nav items is cumbersome, because there are a number of pages that are deliberately excluded from the nav, and the writer has to figure this out.
Discussion from: !4805 (merged)
Marcel:
I wonder if we should consider some metadata in the docs themselves to show which ones shouldn't be in the nav.
If we had some kind of
nav: false
in the metadata, it would make it clear whether or not we expect any particular doc to be in the nav, preventing all these discussions from arising again repeatedly? A future iteration could be to use that metadata as part of the test that generates the "pages not in nav" report?
Advice from Sarah:
We can add whatever metadata we'd like. There aren't any technical/platform reasons blocking us from doing so, as long as we don't use one that collides with core functionality in Hugo (these: https://gohugo.io/content-management/front-matter/). So, all good there.
I do think
nav
as a label might be misleading as to what it does. To me, that would suggest that the nav is auto-generated, and thenav
tag controls that. It's heavier, but maybe something likenav_report_ignore: true
would be clearer.Whatever we go with, we should add it here: https://docs.gitlab.com/ee/development/documentation/metadata.html#additional-metadata
Ignoring pages with that tag from the nav report will be super easy. We already do something like this to ignore pages with a
redirect_to
attribute from the report (here).
Proposal
Metadata sounds like a viable option here:
-
Decide on a suitable name for the metadata -
Add to pages that we know are deliberately excluded from nav. -
Update script to ignore these pages. -
Update docs at https://docs.gitlab.com/ee/development/documentation/metadata.html#additional-metadata -
Update monthly chores template with instructions to add this metadata to any new pages identified as false positive.
If this option doesn't work, alternatives proposed by Lorena:
Also, maybe instead of each TW creating an issue for the month's missing pages, have only one issue where the MM-YYYY represents "last updated", or a spreadsheet with the missing pages and columns with notes about false positives or other reasons why some pages are not added to the nav.