split API reference into modules

[sarah11918]

Description (required)

In an attempt to make the API reference easier to navigate adds a new reference section specifically for the Astro API and each module individually.

Basic infra only! No content changes or improvements attempted! We should use this PR to figure out file name/folder conventions to use! Consistent page titles etc.! No decisions are final!

TRANSLATORS:
I'm sorry that there will still be more work to do after this that will again update the content on some of these pages. And, there is more content changed here than I expected, but most of it is moving content around in sections! You can see the list below for things that I expect to continue to change here, but I did want to get the new pages created first, then we can tackle specific content independently!

• redirects ? I've kept the name of the main API reference page so in the worst case people aren't getting 404s visiting content that has moved. Is having redirect from section headings to a new page practical?
• one error message was force overwritten to pass link checks here; will need to be updated at source once we are confident in what changes this pr actually makes PR
• Page introductions. These were previously sections of a longer page, so they don't really introduce the page nicely at all yet; they start with another heading immediately after the page title etc.
• Lunaria tracking - some translated pages have had links updated but there should be no other changes needed to those pages, so they should be ignored by the tracker. Only the English pages, and the nav should be tracked.

Summary of notes left open below for follow up work:

• remove "built in components" page entirely (already duplication now with the <ViewTransitions>, <Image>, and <Picture> components. Instead, content will go to relevant place in docs, perhaps with a new astro:components page
• assets page needs full documentation of <Image> properties -- copy from guide to start, then actually make proper reference matching the rest of the entries
• for the imported components, and moving to the Components/Syntax page for things like <Fragment> that are not imported
• So far, only middleware documents a required export (vs things you import from the module). Other pages could also document exports, but currently don't. For the sake of this PR, we are not adding new entries but will revisit for consistency and can consider adding the "Exports" section to other pages like astro:actions, astro:content etc.
• sidebar nav huge design means not touching the section headers etc. for Reference. Sidebar will change in current project, so not addressed here
• Is api-reference still the right name for the "leftover page"? Work is ongoing as we speak to clean up and focus the Runtime API page, so naming not changed here (plus, means we don't need any redirects here because the old page still exists). This particular page will be updated separately.
• we noticed (by the fact there were no broken links) that the view transitions guide page does not at any point link to the astro:transitions reference. This should make us check that page to make sure it's not doing too much and trying to be reference itself instead of just linking out to reference. (Note, so many things were previously undocumented about the API that it could simply mean that content just wasn't covered in the guide either, so not necessarily a problem, but for sure a smell.)

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	af5eb10
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/671ba25cc1596a00088d6913
😎 Deploy Preview	https://deploy-preview-9687--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

Locale	File	Note
en	guides/actions.mdx	Source changed, localizations will be marked as outdated.
en	guides/content-collections.mdx	Source changed, localizations will be marked as outdated.
en	guides/imports.mdx	Source changed, localizations will be marked as outdated.
en	guides/internationalization.mdx	Source changed, localizations will be marked as outdated.
en	guides/markdown-content.mdx	Source changed, localizations will be marked as outdated.
en	guides/middleware.mdx	Source changed, localizations will be marked as outdated.
en	reference/api-reference.mdx	Source changed, localizations will be marked as outdated.
en	reference/errors/actions-returned-invalid-data-error.mdx	Source changed, localizations will be marked as outdated.
en	reference/modules/astro-actions.mdx	Source added, will be tracked.
en	reference/modules/astro-assets.mdx	Source added, will be tracked.
en	reference/modules/astro-content.mdx	Source added, will be tracked.
en	reference/modules/astro-i18n.mdx	Source added, will be tracked.
en	reference/modules/astro-middleware.mdx	Source added, will be tracked.
en	reference/modules/astro-transitions.mdx	Source added, will be tracked.
en	tutorials/add-content-collections.mdx	Source changed, localizations will be marked as outdated.
it	tutorials/add-content-collections.mdx	Localization changed, will be marked as complete.
ja	guides/content-collections.mdx	Localization changed, will be marked as complete.
ja	guides/imports.mdx	Localization changed, will be marked as complete. 🔄️
ja	guides/middleware.mdx	Localization changed, will be marked as complete.
ja	reference/configuration-reference.mdx	Localization changed, will be marked as complete.
pl	guides/imports.mdx	Localization changed, will be marked as complete. 🔄️
en	nav.ts	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[delucis]

I think this looks great! Definitely helpful to split these out into the new pages. 🙌

No comment on the Lunaria side of things, but left a couple of notes on things that stood out to me.

[delucis]

And while we’re on the subject of title: if we do indeed come up with a better title (and sidebar label?), we may as well also rename the URL to match and add a redirect.

[delucis]

Love the new intros @sarah11918! Left some more notes. Sorry if some of the headings comments slightly contradict what we discussed previously. Going through things in more details made me realise that clearly labelling with module names may be more important than I initially realised (especially for certain pages).

[delucis]

Don’t want to keep throwing spanners at this very helpful PR, but this page (and how lonely getImage() is on it) is making me wonder about where <Image> and <Picture> are documented.

Right now we have “Built-in Components”, which actually mixes components from a range of sources:

• astro/components (also available as astro:components) exports <Code>, <Prism>, and <Debug>.
• astro:assets exports <Image> and <Picture>.
• astro:transitions exports <ViewTransitions> (being renamed in v5).
• <Fragment> is not imported at all, it’s more of a language/syntax feature.
• <Content> can come from all kinds of places (imported Markdown, rendered content collection entries, etc.)

So this is more a note rather than a suggestion in one way or other. Now we document modules explicitly, maybe the components for that module are helpful in that module’s reference? Flipside of course is that the current component page collects all of the above so someone thinking “What are the available components?” can find them, vs someone looking to answer “What’s in astro:assets?”

[sarah11918]

Yes, this is a lonely page indeed! I think now that we're doing this restructuring, it's probably more helpful to have the components in their own module page?

So, maybe we add an astro:components page for those imported components and move the other components to their respective pages? I think <Content /> and <Fragment> are already documented on the Markdown and Components pages respectively as far as syntax and Markdown imports are concerned.

[Fryuni]

It seems a bit weird to me having a "Reference" group and then a bunch of reference pages outside of that group. The word "reference" is also repeated in multiple links, but not all of them so it is inconsistent.

What if we nest them to keep the context and remove the repetition?

Current	Nested and shortened

Also changed "Error" to "Errors" to match "Directives" when the reference is about multiple things

[delucis]

It seems a bit weird to me having a "Reference" group and then a bunch of reference pages outside of that group. The word "reference" is also repeated in multiple links, but not all of them so it is inconsistent.

I agree, but for context, this version of the sidebar is almost certainly a very short-lived iteration. We’re heading in the direction of something more like: https://docs-sidebar-topics.netlify.app/reference/configuration-reference/