Inconsistent Behavior of Links in Starlight | Frontmatter Prev and Next

[Neonsy]

What version of starlight are you using?

0.22.4

What version of astro are you using?

4.8.6

What package manager are you using?

pnpm

What operating system are you using?

Windows

What browser are you using?

Brave

Describe the Bug

Issue: Inconsistent Behavior of Prev and Next Links in Starlight

Description

I've been experimenting with Starlight for a couple of days and have recently set up a project hosted on GitHub Pages. I've noticed that the behavior of the Prev and Next links is inconsistent and I'm unsure why this is happening.

Details

The issue is that sometimes the links work as expected, and other times they don't. It seems that sometimes they need to be prefixed with the Astro config's base value, and other times they automatically prefix themselves.

To understand why the behavior changes, I created a fresh template install. In this template, I have three files in an auto-generated directory. Each file uses the exact same link. The link in three.md works, but the links in one.md and two.md do not.

In my actual documentation, I've tried prefixing the frontmatter links with the base value. Everything works with this prefixing, except for one file. I've also noticed odd differences where a link works in one test run and not in another. It seems whether the link is treated as relative or absolute, and whether it needs the base as a prefix, changes unpredictably.

Steps to Reproduce

1. Create a fresh Starlight template.
2. Create a directory at /src/content/docs/myfiles within the new project.
3. Add three files (one.md, two.md, three.md) and add them to the sidebar config as auto-generated directory.
4. Use the same link in each file.

---
title: one
sidebar:
    order: 1
next:
    label: example ref
    link: reference/example/
---

---
title: two
sidebar:
    order: 2
next:
    label: example ref
    link: reference/example/
---

---
title: three
sidebar:
    order: 3
next:
    label: example ref
    link: reference/example/
---

6. Observe that the link in three.md works, but the links in one.md and two.md do not.

Expected Behavior

The links should consistently work across all files and should either all require manual prefixing with the base value or non of the links require the prefixing.

Actual Behavior

The links work inconsistently. Sometimes they require manual prefixing with the base value, and other times they do not.

I believe this is not the intended behavior, hence I'm opening this issue. Any help or guidance would be greatly appreciated.

Link to Minimal Reproducible Example

https://stackblitz.com/edit/github-rzkjm9?file=astro.config.mjs

Participation

• I am willing to submit a pull request for this issue.

[delucis]

Thank you for the detailed issue and reproduction @DrNeonsy — extremely helpful!

This behaviour looks like a bug to me although I don’t immediately understand why the different pages are handled differently.

My expectation would be that the value of link should be used as authored, without prefixing base or modifying it. That is in general how we treat links in content, where base needs to be added manually — enabling you to link to / even if the rest of the site is at /some-base/. But might need to double check that against how sidebar config behaves where we add language locales (and I believe base too) automatically — might have my assumptions wrong.

In that case, the “correct” frontmatter would look like (the leading / being important so the link is root-relative and not relative to the current page):

next:
    label: example ref
    link: /my-repo/reference/example/

First things first though is to work out why those two seemingly identical pages behave differently 😅

[Neonsy]

Thank you, @delucis, for taking the time to review my issue. I appreciate your assistance in this matter.

To provide more context, I'd like to share a specific instance from my actual documentation where I've encountered this inconsistent behavior. Despite managing to resolve most of the link-related issues, there's one page that continues with the problematic behavior.

---
title: Numbers
prev:
    label: Output
    link: /Python-Note-Collection/python/basics/output
next:
    label: Datatypes
    link: /python/basics/datatypes
---

This page, in particular, seems to be behaving differently from the rest, and I'm unsure why. As you can see, the prev link requires the base, but the next link does it automatically, meaning if i were to do it the inteded way, it would link to the wrong location. Any insights or guidance you could provide would be greatly appreciated. Thank you again for your time and assistance.

[HiDeoo]

Had a bit of free time so I started investigating it. I did not have time yet to start a PR but wanted to share my findings.

If we take your last example and remove the prev and next frontmatter configuration, the page will automatically generate with a prev link and no next link. This is because the page is the last page of an autogenerated links group (so it has a previous page, but no next page).

When the prev and next frontmatter configuration are set, 2 different code paths are taken:

• prev link:
  • An automatically generated prev link already exists.
  • Edit this link and use prev.label and prev.link from the frontmatter as is.
  • The valid /Python-Note-Collection/python/basics/output link will work.
• next link:
  • An automatically generated next link does not exist.
  • Create a new link with the next.label and next.link from the frontmatter.
  • The makeLink() function will call a formatPath() function using a path formatter that automatically adds the base to the path.
  • The valid /Python-Note-Collection/python/basics/output link will become /Python-Note-Collection/Python-Note-Collection/python/basics/output (and skipping the base using /python/basics/datatypes will become /Python-Note-Collection/python/basics/datatypes and be valid).

In this specific case, we want to use the provided next.link as is so I would guess there are multiple ways to fix this (and did not have time to think about the best way yet):

• Do we really need to always call formatPath() in this specific case?
• Should the base be skipped in formatPath() when the path starts with it?
• Should the base be skipped in formatPath() based on a configuration/flag?

[Neonsy]

Thank you for your detailed investigation @HiDeoo.

I've also noticed that the very last page seems to be the one acting up during my tests, when it comes to the next link, which is consistent with the minimal reproduction example.

However, I must admit that my understanding of the underlying code is limited, so my testing has been somewhat superficial.

Therefore, I once again want to thank you for your findings.

I'm looking forward to how this will play out with keen interest.

[delucis]

Amazing investigation @HiDeoo! Glad that we could trace it down to the cases where a prev/next link would not otherwise exist.

I think that aligns with my expectation then: we accidentally introduced formatPath() in a code path that includes user-authored links, which should not be modified. It’s probably a bit fiddly though — other places makeLink() is used probably do expect path formatting, so we probably need to go through working out which do and which don’t.

Should the base be skipped in formatPath() when the path starts with it?

I think that’s a risky path to go down — not impossible for there to be situations like /base/base, so we should probably always add the base deterministically, not guessing based on path content.