BetonQuest / BetonQuest/mkdocs-snippets

Links seem to adjust one level too high.

Open
#5 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
3
Forks
1
Avg merge
8h 37m
Merged PRs (30d)
1

Description

My MKDocs Material site is hosted from an enterprise GitHub pages site at `https://host.corp/orgName/repoName`. This URL being the root of the docs site. I have a link in a snippet that looks something like below. Instead of rendering the link to `https://host.corp/orgName/repoName/#reporting-feedback`, it instead resolves to `https://host.corp/orgName/index.md#reportingFeedback`.

```YAML
feedbackInstructionsLink: |-
[reporting feedback](index.md#reporting-feedback)
```

When I look in the console, I see this warning that seems to indicate that it's stepping too far back when it adjusts the relative link. I've got absolute link validation set to `relative_to_docs`; but even disabling that setting doesn't seem to have any effect at all. I've also tried different variations in the path and picking different pages that are deeper in the `/docs` folder as a test, but they all generally behave the same way. The behavior is also the same running both locally and as deployed to GitHub pages.

```
WARNING - Doc file 'getting-started/setup/index.md' contains a link '../../../index.md', but the target '../index.md' is not found among
documentation files.
```

Is there something I'm doing wrong, or is this a bug?

Contributor guide

No contributing guide indexed for this repository

Research direction

Reproduce the issue with the shown feedbackInstructionsLink in a MkDocs Material site hosted under /orgName/repoName, both locally and on GitHub Pages. Trace the plugin's relative-link adjustment using the warning for getting-started/setup/index.md as the starting clue. Done means the link resolves to the repository site's root anchor without an incorrect index.md path or warning.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, python
Domain
documentation
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.