Short pathes

[stereobooster]

What version of starlight are you using?

0.24.0

What is your idea?

Ability to configure Starlight to use "short" urls. For example, if I have following files structure:

docs
  reciepes
    backlinks
    diagrams

I want Starlight to generate URLs like this:

• /backlinks instead of /reciepes/backlinks
• /diagrams instead of /reciepes/diagrams

But the same time I would like sidebar to preserve structure.

I can achieve this by using slug in frontmatter:

---
slug: backlinks
---

But I was wondering, if there is a way to make this configuration, so I would not need to place it in every file. Maybe I can configure Astro content (schema) some how?

Why is this feature necessary?

Because I want to move files around without breaking URLs. I could theoretically dump all files at root level, but in this case Sidebar looks pretty bad.

And yes I know that I would need to make sure to have unique file names in this case. And probably this is not the feature that a lot of people would use. But a workaround or plugin would do too - not necessary built-in feature.

Do you have examples of this feature in other projects?

No response

Participation

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

[lorenzolewis]

Hi, @stereobooster !

Would Astro redirects work for you? This would allow you to have the structure you're wanting while retaining the same file structure (or the opposite scenario!)

https://docs.astro.build/en/guides/routing/#redirects

[stereobooster]

The need to maintain list of redirects would be the same amount of work as put slug in frontmatter for every file. I'm looking for easier workaround. Does this make sense?

PS URLs are generated based on slug, but sidebar is generated based on path - based on my experimentation. So putting slug in frontmatter already gives required effect. I'm looking for even simpler way to achieve this

[delucis]

In this area Starlight is mostly limited by how Astro itself manages slugs etc. with content collections. Might be something that could become more flexible with Astro’s work on a new “content layer” API extending content collections — withastro/roadmap#946

[stereobooster]

I hopped something like this would work

// src/plugins/remarkShortSlug.mjs
import { slug as githubSlug } from "github-slugger";
import path from "node:path";

// slug implementation according to Astro
// see astro/packages/astro/src/content/utils.ts
function generateShortSlug(filePath) {
  const withoutFileExt = filePath.replace(
    new RegExp(path.extname(filePath) + "$"),
    ""
  );
  const rawSlugSegments = withoutFileExt.split(path.sep);
  const slug = githubSlug(rawSlugSegments.pop()).replace(/\/index$/, "");
  return slug;
}

export function remarkShortSlug() {
  return function (tree, file) {
    const filepath = file.history[0];
    file.data.astro.frontmatter.slug =
      file.data.astro.frontmatter.slug || generateShortSlug(filepath);
  };
}

// astro.config.mjs
  markdown: {
    remarkPlugins: [
      remarkShortSlug,
    ]
 }

But it doesn't work

[delucis]

Correct. Astro’s content collections process the slug field before any remark/rehype plugins run for performance reasons — otherwise we’d have to render every file with remark/rehype just to know the slugs that exist.

In the future content layer plans I think you’d have more control over this and could create a custom content loader that decides the slug for each file however you like.

[HiDeoo]

Starting with Starlight 0.35.0, a new generateId option was added to Starlight’s docsLoader() to allow for such customizations.

For example, the following code snippet will remove the .md or .mdx extension from the filenames, but otherwise leave them unchanged:

docsLoader({
  // Remove the `.md` or `.mdx` extension, but otherwise don’t process filenames.
  generateId: ({ entry }) => entry.split('.').slice(0, -1).join('.'),
}),

This is a basic example but it could be used to dynamically identify if the entry is part of the reciepes folder, and if it is, generate a different ID for it as suggested in the original question.