If an xref doesn't have an anchor, the link text auto-populates from the topic title.
For example xref:api-reference:overivew.adoc[] generates a link with the text API reference overview (which is the title of the target topic).
However, if the xref has an anchor, the link text doesn't populate.
For example xref:api-reference:overview.adoc#data-api-client[] results in the following:
Because humans are fallible and will inevitably miss things like this amongst a sea of larger changes, I propose two possible solutions for this:
Produce a warning or error in the preview build if link text isn't auto-populated. At minimum, this could specifically look for xrefs containing # where [] is empty. But I don't know how complicated or burdensome such a check might be. Maybe it could be a separate action that runs weekly against main.
Auto-populate the topic title whenever link text isn't supplied (i.e. empty []), regardless of whether there is an anchor or not. I know that if you provide an anchor, you should use the title of the target section, but the topic title would be a better fallback then the raw path (api-reference:overview.adoc#data-api-client).
aimurphy
commented
2 months ago
If an xref doesn't have an anchor, the link text auto-populates from the topic title. For example
xref:api-reference:overivew.adoc[]generates a link with the textAPI reference overview(which is the title of the target topic).However, if the xref has an anchor, the link text doesn't populate. For example
xref:api-reference:overview.adoc#data-api-client[]results in the following:Because humans are fallible and will inevitably miss things like this amongst a sea of larger changes, I propose two possible solutions for this:
Produce a warning or error in the preview build if link text isn't auto-populated. At minimum, this could specifically look for xrefs containing
#where[]is empty. But I don't know how complicated or burdensome such a check might be. Maybe it could be a separate action that runs weekly against main.Auto-populate the topic title whenever link text isn't supplied (i.e. empty
[]), regardless of whether there is an anchor or not. I know that if you provide an anchor, you should use the title of the target section, but the topic title would be a better fallback then the raw path (api-reference:overview.adoc#data-api-client).