Skip to content

rustdoc: add link prefix which would allow overwriting explicit links with item links #127086

Open
@newpavlov

Description

@newpavlov

Many crates use #![doc = include_str("../README.md")] to reduce doc duplication. Unfortunately, it means that we have provide explicit item links:

This crate provides the [`foobar`] function.

[`foobar`]: https://docs.rs/foobar/latest/foobar/fn.foobar.html

It works fine when README is rendered on GitHub or crates.io, but when docs generated by rustdoc we get external item links, which causes a number of issues (e.g. when docs generated offline).

It would be nice if rustdoc recognized a special link prefix which would allow it to overwrite explicit links with auto-generated item links. For example:

This crate provides the [`foobar`][rustdoc:foobar] function.

[rustdoc:foobar]: https://docs.rs/foobar/latest/foobar/fn.foobar.html

[link][rustdoc:item] would be translated to [link](link-to-item) and [rustdoc::item]: explicit-link would be ignored by rustdoc.

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-rustdoc-jsArea: Rustdoc's JS front-endA-rustdoc-uiArea: Rustdoc UI (generated HTML)C-feature-requestCategory: A feature request, i.e: not implemented / a PR.T-rustdocRelevant to the rustdoc team, which will review and decide on the PR/issue.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions