Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

split API reference into modules #9687

Merged
merged 37 commits into from
Oct 25, 2024
Merged
Show file tree
Hide file tree
Changes from 11 commits
Commits
Show all changes
37 commits
Select commit Hold shift + click to select a range
8948760
split api reference into module pages and update nav
sarah11918 Oct 15, 2024
cec5809
fix some links
sarah11918 Oct 15, 2024
20eb0e4
fix more links
sarah11918 Oct 15, 2024
e905a99
fix another link
sarah11918 Oct 15, 2024
7776019
Update actions-returned-invalid-data-error.mdx
sarah11918 Oct 15, 2024
f767e9d
fix last links i hope
sarah11918 Oct 15, 2024
40d042d
rename module files and update links
sarah11918 Oct 15, 2024
ee4aa85
update nav for new file names
sarah11918 Oct 15, 2024
9faccca
Update src/content/docs/en/reference/errors/actions-returned-invalid-…
sarah11918 Oct 15, 2024
8cbaee4
Update src/i18n/en/nav.ts
sarah11918 Oct 16, 2024
9b4505c
Merge branch 'main' into api-modules
sarah11918 Oct 22, 2024
35ea4ba
uniform page introductions
sarah11918 Oct 22, 2024
a2dd075
remove redundant h2 titles and move everything up a heading level
sarah11918 Oct 22, 2024
014240e
fix links
sarah11918 Oct 22, 2024
d3fd512
add max min headings for all module pages
sarah11918 Oct 22, 2024
787921a
update nav and api-reference title
sarah11918 Oct 23, 2024
756da98
Merge branch 'main' into api-modules
sarah11918 Oct 23, 2024
cc00e7f
Apply suggestions from Chris code review
sarah11918 Oct 23, 2024
69926e1
add import section at top of each module page
sarah11918 Oct 23, 2024
f80fdbf
Merge branch 'main' into api-modules
sarah11918 Oct 23, 2024
f2c2253
fix link
sarah11918 Oct 23, 2024
ef348ca
combine imports for astro:content
sarah11918 Oct 24, 2024
027c6c2
fix typos in import sections
sarah11918 Oct 24, 2024
74ab13d
update imports code block for transitions page
sarah11918 Oct 24, 2024
9dd7063
typo in code block
sarah11918 Oct 24, 2024
ce04635
fix other typo
sarah11918 Oct 24, 2024
3f9e1ae
Rework module reference heading hierarchies and split `astro:content`…
delucis Oct 24, 2024
8ed8995
Make the `astro:transitions` reference slightly more truthful
delucis Oct 24, 2024
023633c
fix links
sarah11918 Oct 24, 2024
a53dc59
fix other link
sarah11918 Oct 24, 2024
205f31e
still fixing links
sarah11918 Oct 24, 2024
ba977cf
Update astro:transitions page
Fryuni Oct 24, 2024
20e53c3
use 3.0.0 stable version number
sarah11918 Oct 24, 2024
c31325e
move onRequest out of imports section
sarah11918 Oct 25, 2024
2074e94
Merge branch 'main' into api-modules
sarah11918 Oct 25, 2024
714ddcd
Friday pass
delucis Oct 25, 2024
af5eb10
Merge branch 'main' into api-modules
sarah11918 Oct 25, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions src/content/docs/en/guides/actions.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Use actions instead of API endpoints for seamless communication between your cli

- Automatically validate JSON and form data inputs using [Zod validation](https://zod.dev/?id=primitives).
- Generate type-safe functions to call your backend from the client and even [from HTML form actions](#call-actions-from-an-html-form-action). No need for manual `fetch()` calls.
- Standardize backend errors with the [`ActionError`](/en/reference/api-reference/#actionerror) object.
- Standardize backend errors with the [`ActionError`](/en/reference/modules/astro-actions/#actionerror) object.

## Basic usage

Expand Down Expand Up @@ -129,7 +129,7 @@ Follow these steps to define an action and call it in a `script` tag in your Ast

</Steps>

<ReadMore>See the full Actions API documentation for details on [`defineAction()`](/en/reference/api-reference/#defineaction) and its properties.</ReadMore>
<ReadMore>See the full Actions API documentation for details on [`defineAction()`](/en/reference/modules/astro-actions/#defineaction) and its properties.</ReadMore>

## Organizing actions

Expand Down Expand Up @@ -340,7 +340,7 @@ The following example shows a validated newsletter registration form that accept
}
```

<ReadMore>See the [`input` API reference](/en/reference/api-reference/#input-validator) for all available form validators.</ReadMore>
<ReadMore>See the [`input` API reference](/en/reference/modules/astro-actions/#input-validator) for all available form validators.</ReadMore>

3. Add a `<script>` to the HTML form to submit the user input. This example overrides the form's default submit behavior to call `actions.newsletter()`, and redirects to `/confirmation` using the `navigate()` function:

Expand Down Expand Up @@ -375,7 +375,7 @@ The following example shows a validated newsletter registration form that accept

### Displaying form input errors

You can validate form inputs before submission using [native HTML form validation attributes](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation#using_built-in_form_validation) like `required`, `type="email"`, and `pattern`. For more complex `input` validation on the backend, you can use the provided [`isInputError()`](/en/reference/api-reference/#isinputerror) utility function.
You can validate form inputs before submission using [native HTML form validation attributes](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation#using_built-in_form_validation) like `required`, `type="email"`, and `pattern`. For more complex `input` validation on the backend, you can use the provided [`isInputError()`](/en/reference/modules/astro-actions/#isinputerror) utility function.

To retrieve input errors, use the `isInputError()` utility to check whether an error was caused by invalid input. Input errors contain a `fields` object with messages for each input name that failed to validate. You can use these messages to prompt your user to correct their submission.

Expand Down
10 changes: 5 additions & 5 deletions src/content/docs/en/guides/content-collections.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -312,7 +312,7 @@ relatedPosts:

### Defining custom slugs

When using `type: 'content'`, every content entry generates a URL-friendly `slug` property from its [file `id`](/en/reference/api-reference/#id). The slug is used to query the entry directly from your collection. It is also useful when creating new pages and URLs from your content.
When using `type: 'content'`, every content entry generates a URL-friendly `slug` property from its [file `id`](/en/reference/modules/astro-content/#id). The slug is used to query the entry directly from your collection. It is also useful when creating new pages and URLs from your content.

You can override an entry's generated slug by adding your own `slug` property to the file frontmatter. This is similar to the "permalink" feature of other web frameworks. `"slug"` is a special, reserved property name that is not allowed in your custom collection `schema` and will not appear in your entry's `data` property.

Expand All @@ -326,7 +326,7 @@ Your blog post content here.

## Querying Collections

Astro provides two functions to query a collection and return one (or more) content entries: [`getCollection()`](/en/reference/api-reference/#getcollection) and [`getEntry()`](/en/reference/api-reference/#getentry).
Astro provides two functions to query a collection and return one (or more) content entries: [`getCollection()`](/en/reference/modules/astro-content/#getcollection) and [`getEntry()`](/en/reference/modules/astro-content/#getentry).

```js
import { getCollection, getEntry } from 'astro:content';
Expand All @@ -343,7 +343,7 @@ const allBlogPosts = await getCollection('blog');
const graceHopperProfile = await getEntry('authors', 'grace-hopper');
```

Both functions return content entries as defined by the [`CollectionEntry`](/en/reference/api-reference/#collection-entry-type) type.
Both functions return content entries as defined by the [`CollectionEntry`](/en/reference/modules/astro-content/#collection-entry-type) type.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

### Accessing referenced data

Expand Down Expand Up @@ -438,7 +438,7 @@ const blogEntries = await getCollection('blog');

A component can also pass an entire content entry as a prop.

If you do this, you can use the [`CollectionEntry`](/en/reference/api-reference/#collection-entry-type) utility to correctly type your components props using TypeScript. This utility takes a string argument that matches the name of your collection schema, and will inherit all of the properties of that collection's schema.
If you do this, you can use the [`CollectionEntry`](/en/reference/modules/astro-content/#collection-entry-type) utility to correctly type your components props using TypeScript. This utility takes a string argument that matches the name of your collection schema, and will inherit all of the properties of that collection's schema.
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

```astro /CollectionEntry(?:<.+>)?/
---
Expand Down Expand Up @@ -508,7 +508,7 @@ If your custom slugs contain the `/` character to produce URLs with multiple pat

### Building for server output (SSR)

If you are building a dynamic website (using Astro's SSR support), you are not expected to generate any paths ahead of time during the build. Instead, your page should examine the request (using `Astro.request` or `Astro.params`) to find the `slug` on-demand, and then fetch it using [`getEntry()`](/en/reference/api-reference/#getentry).
If you are building a dynamic website (using Astro's SSR support), you are not expected to generate any paths ahead of time during the build. Instead, your page should examine the request (using `Astro.request` or `Astro.params`) to find the `slug` on-demand, and then fetch it using [`getEntry()`](/en/reference/modules/astro-content/#getentry).


```astro
Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/en/guides/imports.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -246,7 +246,7 @@ Additionally, glob patterns must begin with one of the following:

#### `Astro.glob()` vs `getCollection()`

[Content collections](/en/guides/content-collections/) provide a [`getCollection()` API](/en/reference/api-reference/#getcollection) for loading multiple files instead of `Astro.glob()`. If your content files (e.g. Markdown, MDX, Markdoc) are located in collections within the `src/content/` directory, use `getCollection()` to [query a collection](/en/guides/content-collections/#querying-collections) and return content entries.
[Content collections](/en/guides/content-collections/) provide a [`getCollection()` API](/en/reference/modules/astro-content/#getcollection) for loading multiple files instead of `Astro.glob()`. If your content files (e.g. Markdown, MDX, Markdoc) are located in collections within the `src/content/` directory, use `getCollection()` to [query a collection](/en/guides/content-collections/#querying-collections) and return content entries.

## WASM

Expand Down
8 changes: 4 additions & 4 deletions src/content/docs/en/guides/internationalization.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -60,7 +60,7 @@ The localized folders do not need to be at the root of the `/pages/` folder.

### Create links

With i18n routing configured, you can now compute links to pages within your site using the helper functions such as [`getRelativeLocaleUrl()`](/en/reference/api-reference/#getrelativelocaleurl) available from the [`astro:i18n` module](/en/reference/api-reference/#internationalization-astroi18n). These generated links will always provide the correct, localized route and can help you correctly use, or check, URLs on your site.
With i18n routing configured, you can now compute links to pages within your site using the helper functions such as [`getRelativeLocaleUrl()`](/en/reference/modules/astro-i18n/#getrelativelocaleurl) available from the [`astro:i18n` module](/en/reference/modules/astro-i18n/#internationalization-astroi18n). These generated links will always provide the correct, localized route and can help you correctly use, or check, URLs on your site.

You can also still write the links manually.

Expand Down Expand Up @@ -197,7 +197,7 @@ export default defineConfig({
})
```

Astro provides helper functions for your middleware so you can control your own default routing, exceptions, fallback behavior, error catching, etc: [`redirectToDefaultLocale()`](/en/reference/api-reference/#redirecttodefaultlocale), [`notFound()`](/en/reference/api-reference/#notfound), and [`redirectToFallback()`](/en/reference/api-reference/#redirecttofallback):
Astro provides helper functions for your middleware so you can control your own default routing, exceptions, fallback behavior, error catching, etc: [`redirectToDefaultLocale()`](/en/reference/modules/astro-i18n/#redirecttodefaultlocale), [`notFound()`](/en/reference/modules/astro-i18n/#notfound), and [`redirectToFallback()`](/en/reference/modules/astro-i18n/#redirecttofallback):


```js title="src/middleware.js"
Expand All @@ -216,7 +216,7 @@ export const onRequest = defineMiddleware(async (ctx, next) => {

The [`middleware`](#middleware-function) function manually creates Astro's i18n middleware. This allows you to extend Astro's i18n routing instead of completely replacing it.

You can run `middleware` with [routing options](#routing) in combination with your own middleware, using the [`sequence`](/en/reference/api-reference/#sequence) utility to determine the order:
You can run `middleware` with [routing options](#routing) in combination with your own middleware, using the [`sequence`](/en/reference/modules/astro-middleware/#sequence) utility to determine the order:

```js title="src/middleware.js"
import {defineMiddleware, sequence} from "astro:middleware";
Expand Down Expand Up @@ -342,7 +342,7 @@ export default defineConfig({
})
```

When using functions from the [`astro:i18n` virtual module](/en/reference/api-reference/#internationalization-astroi18n) to compute valid URL paths based on your configuration (e.g. `getRelativeLocaleUrl()`), [use the `path` as the value for `locale`](/en/reference/api-reference/#getlocalebypath).
When using functions from the [`astro:i18n` virtual module](/en/reference/modules/astro-i18n/#internationalization-astroi18n) to compute valid URL paths based on your configuration (e.g. `getRelativeLocaleUrl()`), [use the `path` as the value for `locale`](/en/reference/modules/astro-i18n/#getlocalebypath).

#### Limitations

Expand Down
2 changes: 1 addition & 1 deletion src/content/docs/en/guides/markdown-content.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ const posts = Object.values(await import.meta.glob('../posts/*.md', { eager: tru

When fetching data from your collections via helper functions, your Markdown's frontmatter properties are available on a `data` object (e.g. `post.data.title`). Additionally, `body` contains the raw, uncompiled body content as a string.

<ReadMore>See the full [CollectionEntry type](/en/reference/api-reference/#collection-entry-type).</ReadMore>
<ReadMore>See the full [CollectionEntry type](/en/reference/modules/astro-content/#collection-entry-type).</ReadMore>
sarah11918 marked this conversation as resolved.
Show resolved Hide resolved

#### Importing Markdown

Expand Down
4 changes: 2 additions & 2 deletions src/content/docs/en/guides/middleware.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Middleware also allows you to set and share request-specific information across
<Steps>
1. Create `src/middleware.js|ts` (Alternatively, you can create `src/middleware/index.js|ts`.)

2. Inside this file, export an [`onRequest()`](/en/reference/api-reference/#onrequest) function that can be passed a [`context` object](#the-context-object) and `next()` function. This must not be a default export.
2. Inside this file, export an [`onRequest()`](/en/reference/modules/astro-middleware/#onrequest) function that can be passed a [`context` object](#the-context-object) and `next()` function. This must not be a default export.

```js title="src/middleware.js"
export function onRequest (context, next) {
Expand Down Expand Up @@ -158,7 +158,7 @@ Then, inside the middleware file, you can take advantage of autocompletion and t

## Chaining middleware

Multiple middlewares can be joined in a specified order using [`sequence()`](/en/reference/api-reference/#sequence):
Multiple middlewares can be joined in a specified order using [`sequence()`](/en/reference/modules/astro-middleware/#sequence):

```js title="src/middleware.js"
import { sequence } from "astro:middleware";
Expand Down
Loading
Loading