docs: better explanation for base configuration

[ematipico]

Changes

The documentation wasn't extensive enough IMHO. I didn't understand that config.base is also manipulated by Astro accordingly, this is important because base is read by integrations too.

I also added some practical examples.

Testing

N/A

Docs

/cc @withastro/maintainers-docs for feedback!

[changeset-bot]

🦋 Changeset detected

Latest commit: e5f96af

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[bluwy]

I don't think we need a changeset for this change, but otherwise lgtm! Would also be good to have a pass from docs before merging too.

[delucis]

When does Astro manipulate config.base? And can we avoid doing so? It seems bad practice for us to mutate user config like that, but if it is required, these docs should probably say WHEN that happens. I’m guessing in astro:config:setup it hasn’t happened yet? Because then it would have happened before another integration has the chance to set base itself. So now we potentially have a pretty painful docs problem of “config.base can be different depending on when you read it”.

[sarah11918]

For the sake of a quick, helpful PR to docs that is an improvement, I've made some suggestions below that I think can work in the short term.

But after talking with @delucis, I do think we need a more extensive look at this to consider this behaviour fully documented!

[ematipico]

When does Astro manipulate config.base? And can we avoid doing so? It seems bad practice for us to mutate user config like that, but if it is required, these docs should probably say WHEN that happens. I’m guessing in astro:config:setup it hasn’t happened yet? Because then it would have happened before another integration has the chance to set base itself. So now we potentially have a pretty painful docs problem of “config.base can be different depending on when you read it”.

To be honest, I don't know when Astro does the manipulation, but I found this when I was testing a vite plugin, and the plugin received the base that was already manipulated. So I can assume that the manipulation occurs before starting vite. This is a guess.

[sarah11918]

One missing word commented in below, but then Docs is happy with this PR! Would be nice to more fully understand exactly what's happening for documenting more fully later, but I think this is a helpful update as is!