Closes #3227

This PR makes it possible to pass generateId to Starlight’s docsLoader().

Currently, using generateId to customize content slugs is only possible by ejecting back up to Astro’s generic glob() loader, but this requires figuring out the pattern and base Starlight uses if you want to mirror the docsLoader() behaviour, e.g.:

-   loader: docsLoader(),
+   loader: glob({
+     pattern: "**/[^_]*.{md,mdx}",
+     base: "./src/content/docs",
+     generateId: customMethod
+   }),

After this PR you can keep using docsLoader(), and just add your ID method:

-   loader: docsLoader(),
+   loader: docsLoader({ generateId: customMethod }),

I did not also add an equivalent method to the i18nLoader as customizing slugs for languages seems much less common, and it would be more liable to break given how we load translation files in non-content collection contexts.

A big part of this PR was also figuring out how best to document this, as we currently only document our loaders in passing. This PR adds a “Configuring content collections” section to the config reference which documents all our loaders and schemas. I kept this minimal for now and linked out to existing relevant docs rather than duplicating or moving things around, but I’d welcome feedback on this new section.

It’s perhaps worth noting that there is some risk in supporting custom generateId methods. Especially for multilingual sites.

There are a few code paths running outside of the Astro/Vite context where Starlight uses raw file paths directly rather than the content collection ID. This is notably the case for remark/rehype plugins. For example, we use the file path to work out the current language for remark plugins. This means it won’t be possible to use generateId for entirely novel structures like storing localized content in sub-directories or something.

For example, moving the locale from a file name to the front of the ID like this wouldn’t work for our remark plugins:

// Example input: { entry: 'tutorials/intro/en.md' }
generateId: ({ entry }) => {
  const extensionlessPath = entry.split('.').slice(0, -1).join('.'); // "tutorials/intro/en"
  const segments = extensionlessPath.split('/');                     // ["tutorials", "intro", "en"]
  return [segments.at(-1), ...segments.slice(0, -1)].join('/');      // "en/tutorials/intro"
},

But for common scenarios like preserving uppercase characters or special characters like . inside IDs, it should work pretty OK although it is likely to break compatibility with plugins like https://github.com/HiDeoo/starlight-links-validator that rely on being able to predict the ID format based on the filepath.