Use link title from xrefmap.yml (feature request)
- Dominant language
- C#
- Stars
- 4.4k
- Forks
- 890
- Avg merge
- 2h 11m
- Merged PRs (30d)
- 10
Description
**Operation System**: Windows
**DocFX Version Used**: 2.40.12.0
**Template used**: default
**Steps to Reproduce**:
1. Define a link reference in `xrefmap.yml`:
```yaml
references:
- uid: rfc6238
name: RFC 6238
href: https://www.rfc-editor.org/rfc/rfc6238.txt
fullName: "M'Raihi, D., Machani, S., Pei, M., and J. Rydell, \"TOTP: Time-Based One-Time Password Algorithm\", RFC 6238, DOI 10.17487/RFC6238, May 2011, ."
```
Note: I don't know whether `fullName` is a good property for this feature. Perhaps it should be `title` or `linkTitle` or `description` instead.
2. Refer to `xrefmap.yml` from `docfx.json`:
```json
{
"build": {
…
"xref": [
"xrefmap.yml"
],
…
}
}
```
3. Refer to `xref:rfc6238` from `articles/intro.md`:
```markdown
Link to [RFC 4226].
Link to .
[RFC 4226]: "M'Raihi, D., Bellare, M., Hoornaert, F., Naccache, D., and O. Ranen, \"HOTP: An HMAC-Based One-Time Password Algorithm\", RFC 4226, DOI 10.17487/RFC4226, December 2005, ."
```
4. Run `docfx build`.
**Expected Behavior**:
The title defined in `xrefmap.yml` shows up in the HTML `title` attribute:
```html
Link to RFC 4226.
Link to RFC 6238.
```
**Actual Behavior**:
The xref link has no HTML `title` attribute:
```html
Link to RFC 4226.
Link to RFC 6238.
```
**Rationale**:
Pro: This would make it easier to ensure that all hyperlinks to the same external site have the same title. Currently, the easiest way to do that seems `find . -name "*.md" -print0 | xargs -0 -r grep '^\[\([^][]\|\\.\)\+\]:' | sort -u`.
Pro: This would also make it easier to link to a bug-tracking system and copy the bug titles to link titles.
Con: I'm not sure whether Safari on iOS can display link titles at all. Users of mobile devices might not benefit from such a change.
Con: If a documentation set were ported from normal Markdown reference links to xref links in order to use this feature, not all Markdown authoring tools would be able to preview the links correctly. In this respect, it might be better to have a bot update the link titles in each Markdown file.
Workaround: Create a separate file just for the link and use [inline file inclusion](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#inline) to embed the link into each article that needs it. However, this does not let the articles change the link text, which can be a problem if the sentence needs a different grammatical case.
Alternative feature: Create a separate file for the [link reference definition](https://spec.commonmark.org/0.28/#link-reference-definition), use [block file inclusion](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#block) to load the link reference definition to each article that needs it, and use a reference link. This does not currently work in DocFX because link reference definitions in included files are not visible to the including file.
[docfx_project.zip](https://github.com/dotnet/docfx/files/3026342/docfx_project.zip) demonstrates several of these approaches.
Contributor guide
Assessment
This issue has not been assessed yet.