DOP-3211: ref label

[mmeigs]

Ticket

DOP-3211

Notes

Creating a reference that doesn't precede a heading and then attempts to reference that target without providing a label does not emit an error. It successfully builds, but the ref has no children to render, leaving the user with a visually empty spot where a link should be.

Through my investigation I found many instances of this stemming from the one bug report. As many as eleven invisible refs in docs-mongodb-internal alone. This error will help content writers to identify before production.

Examples

Current site

• Above the text Documentation of JavaScript methods and helpers in the legacy mongo shell. there should be a link to the mongo legacy shell. This is one such example of an invisible ref.

Three in quick succession on current docs site

• Search for the text A JavaScript function that associates
• There are three invisible refs in quick succession here
• In the description column of map, reduce, and out - you will see "See for more information"

The refs without labels that are causing this are seen here, here, and here.

And the target refs they are pointing to (which do not have headers directly below) are seen in a row here.

They all three point to starting lines in the same file, however none of these directly precede a header.

---

A/C:

• :ref:s that cannot be rendered due to a lack of label emit an error in the parser log

[i80and]

Oh this is good! If I'm going to nitpick, "Ref" might be a big jargony in the error message "Ref found without text".

Perhaps "Reference found without label" would be better. It would be cool if we could use the did_you_mean() mechanism, but I think that would be a bit dicey here and now.

[mmeigs]

Oh this is good! If I'm going to nitpick, "Ref" might be a big jargony in the error message "Ref found without text".

Perhaps "Reference found without label" would be better. It would be cool if we could use the did_you_mean() mechanism, but I think that would be a bit dicey here and now.

Gotcha, makes sense! And I would love to have a use of did_you_mean, but you're right, especially for me being new-ish to the parser, that seems like a twisty add-on. I'll make a ticket in the backlog though! Whenever there's time that would be a fun little excursion.