A new macro to crossref page titles

[yarusome]

There're various macros for crossrefs to specced definitions (e.g. {{DOMXref}} for Web APIs), but none works for referring to a page such as Applying SVG effects to HTML content, and writers have to manually create a Markdown link in this case.

Most such links have a text identical to the linked page's title, however page titles can change over time, and it's both impractical and unnecessary to require a writer that changes even a single page title to also change every occurrence of this title on other pages. (The situation is even more serious for l10n contents as there're much fewer people there.)

Therefore, I propose to add a new macro {{Title}} (name to be settled down later):

{{Title($1, $2)}}

where:

• $1: the link (without a locale) of which the page title is to be shown, e.g. "/docs/Web/SVG/Applying_SVG_effects_to_HTML_content". (Is the /docs part even necessary?)
• $2 (optional): a boolean value indicating if the title's case needs changing to lower case. Defaults to false.

This macro can reuse the code of existing macros like {{CSSXref}} as it simply fetches the title key from the front matter.

Note:

1. A similar macro {{ShortTitle}} can also be considered, but I doubt how useful it would be.
2. I was thinking to have another parameter between $1 and $2 whose value is an anchor on the page and the macro returns the heading for that anchor, but dropped this part as such info isn't available from the front matter.

[Josh-Cena]

What you are looking for is exactly the Link macro, which was removed in mdn/yari#7237 because there's really no value in using it over Markdown links, other than to save a few characters...

[yarusome]

My concern is about overly easy desync of Markdown link texts instead of saving a few characters. (It doesn't really save.)

The discussion only mentioned the macro as a "Wikimedia era remnant". @teoli2003, could you shed some light here, please? 🙏

[OnkarRuikar]

Not all markdown links that point to a page use the same page's title as the link text, e.g.

SVGs are powerful. You can apply most of the SVG's cool effects to HTML content as well.

Also, what about if we want to link to a section on the page, for example Web/SVG/Applying_SVG_effects_to_HTML_content#example_clipping.
Is the macro supposed to infer the section title in such case? Once the section title has changed(which happens more often than page titles) there is no way for yari to infer title. Unfortunately it has to be manually done.
Once the mdn/content#25421 completes reporting errors will be automated. PR companion will tell you, "by changing section title you've broken these fragments in these files..."

---

What if we automate this instead?
If a PR updates title text then 'updating old title text to new one repo wide' can be automated by looking at git diff to get old and new title text and do search-replace operation repo wide. We can write a custom tool, like we we have for moving pages deleting pages etc.

[yarusome]

Not all markdown links that point to a page use the same page's title as the link text

Yes, that's why this proposal was limited to link texts identical to page titles :)

What if we automate this instead? If a PR updates title text then 'updating old title text to new one repo wide' can be automated by looking at PR's base commit(to get old title) and latest commit(to get new title) and do search-replace operation.

This is good, but lacks the granularity of case-changing (or is it unnecessary as well?) (But I wonder what's the guideline to decide what postprocessing should be done in yari and what in content.)

Once the mdn/content#25421 completes reporting errors will be automated. PR companion will tell you, "by changing section title you've broken these fragments in these files..."

That's fantastic 💯

---

In short, my idea was to minimize the effect of changing titles across pages, which unfortunately left section headings behind. But it's also good to have a system to report affected pages instead.

[bsmth]

Thanks, all. I think I can close as resolved for now. At the time of writing, we have tests in CI for broken link checks -> mdn/content#31265 and as Josh mentioned, we're not likely to add more macros for the time being.