Link directly to targets

[gregsdennis]

With the spec docs now in markdown and with us self-hosting the files, should we move to having links go directly to their targets rather than to an appendix (which is IETF style)? Personally, I never liked linking to an appendix.

OpenAPI uses direct links, which you can see with the JSON Schema spec link in Section 4.4.

[jdesrosiers]

I agree. The appendix is unnecessary.

[gregsdennis]

I'm happy for anyone who wants to do this to take it.

For references to specific sections of the target, the links should go directly to that section (or as close as possible).

[SanidhyaMadheshia]

I think an appendix is not preferred by many contributors . And if direct linking enhances usability without sacrificing clarity, it could be a beneficial shift.

[gregsdennis]

@jdesrosiers do we have support in the markdown processor to link between files? For example, if I wanted to reference the security concerns section in Core from Validation, could I do something like [Security Concerns in Core](core.md#security) or {{core#security}}?

[jdesrosiers]

No, that feature only works on the local page. I looked into it last time you asked about that. I learned a lot about how it could be done, but don't have a solution yet. It's one of the many things I'm trying to juggle right now.

[gregsdennis]

Question of preference:

The current appendix entries link to RFC catalog pages rather than directly to the docs themselves. The benefit of this is that the user can decide what document format they want. The detriment is that there's not a way to link directly to a section within a document.

For example, we have a link like

[section 3.5 of RFC 3986](#rfc3986)

for which the appendix entry is

https://www.rfc-editor.org/info/rfc3986

As part of this, I think it would be beneficial if we can link directly to section 3.5, which has a URL of

https://www.rfc-editor.org/rfc/rfc3986.html#section-3.5

Note that the path has changed: /info/rfc{number} -> /rfc/rfc{number}.html

If we decide to link to the section directly, does it make sense to use the direct-to-document link for all of them?

[gregsdennis]

There are also quite a few places where we're repeating links. I definitely think we can eliminate some of this, but I'm not sure to what degree. Sane approaches:

• link the first time it appears in the document, remaining references are plain text
• link the first time it appears in the section (maybe limit to the nearest <h3>?)