Skip to content

Auto link extras: fail on bad path#2212

Open
ftes wants to merge 1 commit intoelixir-lang:mainfrom
ftes:feature/autolink-fail-bad-path
Open

Auto link extras: fail on bad path#2212
ftes wants to merge 1 commit intoelixir-lang:mainfrom
ftes:feature/autolink-fail-bad-path

Conversation

@ftes
Copy link
Contributor

@ftes ftes commented Mar 16, 2026

Verify paths in links to :extras pages when the link includes a directory component.
Doesn't affect bare filename links such as test.md.

Before

Before this change, ExDoc effectively matched extra links by Path.basename(path), so a link like [Guide](guides/bad_dir/guide.md) could still resolve if there was any extra named guide.md in the flattened output namespace.

After

After this change, ExDoc keeps bare filename links as the legacy flattened lookup, but treats links with a directory component as path-qualified and resolves them through the extra source tree instead.

Design Decision

The main design question in this PR is how to interpret links to extras depending on the shape of the markdown path.

Link form Example Lookup base before Lookup base after
Bare filename [Intro](intro.md) Flattened output filename Flattened output filename
Implicit path [Intro](guides/intro.md) Flattened output filename Current extra source file directory
Explicit relative path [Intro](../guides/intro.md) Flattened output filename Current extra source file directory
Explicit absolute-style path [Intro](/guides/intro.md) Flattened output filename Project root

More concretely, if the current extra source file is guides/current.md:

Link Resolves after this PR
intro.md legacy flattened lookup for intro.md
./intro.md guides/intro.md
guides/intro.md guides/guides/intro.md
../guides/intro.md guides/intro.md
/guides/intro.md guides/intro.md from project root

So guides/intro.md is not project-root-relative. Only /guides/intro.md is.

This keeps the legacy behavior for bare filename links while making path-qualified links fail loudly when the specified path is wrong.

@github-actions
Copy link

github-actions bot commented Mar 16, 2026

@ftes ftes force-pushed the feature/autolink-fail-bad-path branch from 2b4364e to 41bbea2 Compare March 17, 2026 20:22
@ftes ftes marked this pull request as ready for review March 17, 2026 20:30
@ftes ftes force-pushed the feature/autolink-fail-bad-path branch 3 times, most recently from ac71531 to 6bfb370 Compare March 17, 2026 20:47
@ftes ftes force-pushed the feature/autolink-fail-bad-path branch from 6bfb370 to 25c7159 Compare March 17, 2026 21:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant