Skip to content

Commit 30743be

Browse files
FredKSchottmatthewpnatemoo-reNate Mooresarah11918
authored
Deploy v0.26 documentation updates (#294)
* Make Astro.request RFC changes (#270) * Server-side rendering docs (#255) This documents how to setup and use SSR features in Astro. * Fix branch * Update API Reference (#291) * update API reference * Update Astro.slots reference * Update Astro.request and Astro.canonicalURL * remove Astro.resolve section Co-authored-by: Matthew Phillips <matthew@skypack.dev> * chore: update configuring Astro guide * New config documentation (#293) * Changed all astro.config references to .mjs (#283) * Changed all config references to mjs * removed changes here since auto generated * Update src/pages/en/guides/configuring-astro.md Co-authored-by: Erika <3019731+Princesseuh@users.noreply.github.com> Co-authored-by: Erika <3019731+Princesseuh@users.noreply.github.com> * import[dot]meta[dot]env (#286) * new config Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Co-authored-by: Erika <3019731+Princesseuh@users.noreply.github.com> * update migration guide * Update config.ts Co-authored-by: Matthew Phillips <matthew@skypack.dev> Co-authored-by: Nate Moore <natemoo-re@users.noreply.github.com> Co-authored-by: Nate Moore <nate@skypack.dev> Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Co-authored-by: Erika <3019731+Princesseuh@users.noreply.github.com>
1 parent 9270419 commit 30743be

13 files changed

Lines changed: 655 additions & 218 deletions

File tree

‎scripts/docgen.mjs‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ import fetch from 'node-fetch';
33
import jsdoc from 'jsdoc-api';
44

55
// Fill this in to test a response locally, with fetching.
6-
const STUB = ``;
6+
const STUB = ``; // fs.readFileSync('/PATH/TO/MONOREPO/astro/packages/astro/src/@types/astro.ts', {encoding: 'utf-8'});
77

88
const HEADER = `---
99
# NOTE: This file is auto-generated from 'scripts/docgen.mjs'
@@ -15,7 +15,7 @@ setup: |
1515
import Since from '../../../components/Since.astro';
1616
---
1717
18-
The following reference covers all supported configuration options in Astro. To learn more configuring Astro, read our guide on [Configuring Astro](/en/guides/configuring-astro/).
18+
The following reference covers all supported configuration options in Astro. To learn more about configuring Astro, read our guide on [Configuring Astro](/en/guides/configuring-astro/).
1919
2020
\`\`\`js
2121
// astro.config.mjs
@@ -51,6 +51,9 @@ export async function run() {
5151
for (const comment of allParsedComments) {
5252
if (comment.kind === 'heading') {
5353
result += (`## ${comment.name}\n\n`);
54+
if (comment.description) {
55+
result += comment.description.trim() + '\n\n';
56+
}
5457
continue;
5558
}
5659
const cliFlag = comment.tags.find(f => f.title === 'cli');
@@ -65,7 +68,7 @@ export async function run() {
6568
? typerawFlag.text.replace(/\{(.*)\}/, '$1')
6669
: comment.type.names.join(' | ');
6770
result += [
68-
`### ${comment.name}`,
71+
`### ${comment.longname}`,
6972
``,
7073
`<p>`,
7174
``,

‎src/components/UIString.astro‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,4 @@ export interface Props {
55
key: Keys;
66
}
77
---
8-
{useTranslations(Astro)(Astro.props.key)}
8+
{useTranslations(Astro)(Astro.props.key)}

‎src/layouts/MainLayout.astro‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,12 @@ import { SITE } from '../config.ts';
99
import { getLanguageFromURL } from '../util.ts';
1010
1111
const { content = {}, hideRightSidebar = false } = Astro.props;
12-
const currentPage = Astro.request.url.pathname;
12+
const url = new URL(Astro.request.url);
13+
const currentPage = url.pathname;
1314
const currentFile = `src/pages${currentPage.replace(/\/$/, '')}.md`;
1415
const githubEditUrl = `https://github.com/withastro/docs/blob/main/${currentFile}`;
1516
const formatTitle = (content, SITE) => (content.title ? `${content.title} 🚀 ${SITE.title}` : SITE.title);
16-
const lang = getLanguageFromURL(Astro.request.url.pathname);
17+
const lang = getLanguageFromURL(url.pathname);
1718
---
1819

1920
<html dir={content.dir ?? 'ltr'} {lang} class="initial">

‎src/layouts/SplashLayout.astro‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import { SITE } from '../config.ts';
55
import { getLanguageFromURL } from '../util.ts';
66
77
const { title, dir = 'ltr' } = Astro.props;
8-
const lang = getLanguageFromURL(Astro.request.url.pathname);
8+
const lang = getLanguageFromURL(new URL(Astro.request.url).pathname);
99
---
1010

1111
<html {dir} {lang} class="initial">

‎src/pages/de/core-concepts/routing.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -40,14 +40,14 @@ Angenommen du hast eine Seite `pages/post/[pid].astro`:
4040
```astro
4141
---
4242
// Beispiel: src/pages/post/[pid].astro
43-
const {pid} = Astro.request.params;
43+
const {pid} = Astro.params;
4444
---
4545
<p>Post: {pid}</p>
4646
```
4747

48-
Allen Routen mit z. B. `/post/1`, `/post/abc` etc. werden `pages/post/[pid].astro` entsprechen. Jeder passende Pfad-Parameter wird an die Page-Komponente unter `Astro.request.params` weitergegeben.
48+
Allen Routen mit z. B. `/post/1`, `/post/abc` etc. werden `pages/post/[pid].astro` entsprechen. Jeder passende Pfad-Parameter wird an die Page-Komponente unter `Astro.params` weitergegeben.
4949

50-
Zum Beispiel wird die Route `/post/abc` das folgende `Astro.request.params`-Objekt zur Verfügung halten:
50+
Zum Beispiel wird die Route `/post/abc` das folgende `Astro.params`-Objekt zur Verfügung halten:
5151

5252
```json
5353
{ "pid": "abc" }

‎src/pages/en/guides/configuring-astro.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -74,12 +74,12 @@ You can also provide type definitions manually to VSCode, using this JSDoc notat
7474
7575
## Referencing Relative Files
7676
77-
If you provide a relative path to `projectRoot` or the `--project-root` CLI flag, Astro will resolve it against the current working directory where you ran the `astro` CLI command.
77+
If you provide a relative path to `root` or the `--root` CLI flag, Astro will resolve it against the current working directory where you ran the `astro` CLI command.
7878
7979
```js
8080
export default defineConfig({
8181
// Resolves to the "./foo" directory in your current working directory
82-
projectRoot: 'foo'
82+
root: 'foo'
8383
})
8484
```
8585
@@ -88,9 +88,9 @@ Astro will resolve all other relative file and directory strings as relative to
8888
```js
8989
export default defineConfig({
9090
// Resolves to the "./foo" directory in your current working directory
91-
projectRoot: 'foo',
91+
root: 'foo',
9292
// Resolves to the "./foo/public" directory in your current working directory
93-
public: 'public',
93+
publicDir: 'public',
9494
})
9595
```
9696
@@ -99,9 +99,9 @@ To references a file or directory relative to the configuration file, use `impor
9999
```js
100100
export default defineConfig({
101101
// Resolves to the "./foo" directory, relative to this config file
102-
projectRoot: new URL("./foo", import.meta.url),
102+
root: new URL("./foo", import.meta.url),
103103
// Resolves to the "./public" directory, relative to this config file
104-
public: new URL("./public", import.meta.url),
104+
publicDir: new URL("./public", import.meta.url),
105105
})
106106
```
107107

‎src/pages/en/guides/server-side-rendering.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
---
2+
layout: ~/layouts/MainLayout.astro
3+
title: Server-side Rendering (experimental)
4+
---
5+
6+
**Server-side Rendering**, aka SSR, is enabled in Astro behind an experimental flag. When you enable SSR you can:
7+
8+
- Implement sessions for login state in your app.
9+
- Render data from an API called dynamically with `fetch`.
10+
- Deploy your site to a host using an *adapter*.
11+
12+
> SSR is marked as __experimental__ in Astro and changes will occur before it becomes stable. Use only if you can handle API changes.
13+
14+
## Enabling SSR in Your Project
15+
16+
To enable SSR you need to use an adapter. The following adapters are available today with more to come in the future:
17+
18+
- [Netlify](https://github.com/withastro/astro/tree/main/packages/integrations/netlify)
19+
- [Node.js](https://github.com/withastro/astro/tree/main/packages/integrations/node)
20+
21+
In this example we will use `@astrojs/netlify` to build for Netlify. First install the adapter:
22+
23+
```bash
24+
npm install --save-dev @astrojs/netlify
25+
```
26+
27+
Once your packages have been installed, add two new lines to your `astro.config.mjs` project configuration file.
28+
29+
```diff
30+
// astro.config.mjs
31+
import { defineConfig } from 'astro/config';
32+
+ import netlify from '@astrojs/netlify/functions';
33+
34+
export default defineConfig({
35+
+ adapter: netlify(),
36+
});
37+
```
38+
39+
With Netlify you can deploy from git, their web UI, or from the cli. Here we'll use the [Netlify CLI](https://docs.netlify.com/cli/get-started/) to deploy.
40+
41+
First build your site as normal:
42+
43+
```bash
44+
npm run build
45+
```
46+
47+
This creates `netlify/functions/` which contains your SSR code. Deploying your site will deploy this function which contains all of your Astro pages ready to be rendered.
48+
49+
```bash
50+
netlify deploy
51+
```
52+
53+
After the deploy is complete it should provide you a preview URL to see your site.
54+
55+
## Features
56+
57+
Astro will remain a static-site generator by default, but once you enable a server-side rendering adapter a few new features become available to you.
58+
59+
### Astro.request.headers
60+
61+
The headers for the request are available on `Astro.request.headers`. It is a [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) object, a Map-like object where you can retrieve headers such as the cookie.
62+
63+
```astro
64+
---
65+
const cookie = Astro.request.headers.get('cookie');
66+
// ...
67+
---
68+
<html>
69+
<!-- Page here... -->
70+
</html>
71+
```
72+
73+
### Astro.redirect
74+
75+
On the `Astro` global, this method allows you to redirect to another page. You might do this after checking if the user is logged in by getting their session from a cookie.
76+
77+
```astro
78+
---
79+
import { isLoggedIn } from '../utils';
80+
81+
const cookie = Astro.request.headers.get('cookie');
82+
83+
// if the user is not logged in, redirect them to the login page.
84+
if(!isLoggedIn(cookie)) {
85+
return Astro.redirect('/login');
86+
}
87+
---
88+
<html>
89+
<!-- Page here... -->
90+
</html>
91+
```
92+
93+
### Response
94+
95+
You can also return a [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) from any page. You might do this to return a 404 on a dynamic page after looking up an id in the database.
96+
97+
__[id].astro__
98+
99+
```astro
100+
---
101+
import { getProduct } from '../api';
102+
103+
const product = await getProduct(Astro.params.id);
104+
105+
// No product found
106+
if(!product) {
107+
return new Response(null, {
108+
status: 404,
109+
statusText: 'Not found'
110+
});
111+
}
112+
---
113+
<html>
114+
<!-- Page here... -->
115+
</html>
116+
```
117+
118+
#### API Routes
119+
120+
A [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) can also be returned from an API route.
121+
122+
```js
123+
import { getProduct } from '../db';
124+
125+
export function get({ id }) {
126+
const product = await getProduct(id);
127+
128+
if(!product) {
129+
return new Response(null, {
130+
status: 404,
131+
statusText: 'Not found'
132+
});
133+
}
134+
135+
return new Response(JSON.stringify(product), {
136+
status: 200
137+
});
138+
}
139+
```

‎src/pages/en/migrate.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,81 @@ This guide exists to help you migrate to the latest versions of Astro and keep y
88

99
While we try to keep breaking changes to a minimum, we still expect some breaking changes before we hit a v1.0 release. Read the guide below for major highlights and instructions on updating breaking changes.
1010

11+
## Migrate to v0.26
12+
### New Configuration API
13+
14+
Our Configuration API has been redesigned to solve a few glaring points of confusion that had built up over the last year. Most configuration has just been moved or renamed, which will hopefully be a quick update for most users. A few options have been refactored more heavily, and may require a few additional changes:
15+
16+
- `.buildOptions.site` has been replaced with `.site` (your deployed domain) and a new `.base` (your deployed subpath) option.
17+
- `.markdownOptions` has been replaced with `.markdown`, a mostly similar config object with some small changes to simplify Markdown configuration.
18+
- `.sitemap` has been moved into the [@astrojs/sitemap](https://www.npmjs.com/package/@astrojs/sitemap) integration.
19+
20+
If you run Astro with legacy configuration, you will see a warning with instructions on how to update. See our updated [Configuration Reference](/en/reference/configuration-reference/) for more information on upgrading.
21+
22+
Read [RFC0019](https://github.com/withastro/rfcs/blob/main/proposals/0019-config-finalization.md) for more background on these changes.
23+
24+
### New Markdown API
25+
26+
Astro v0.26 releases a brand new Markdown API for your content. This included three major user-facing changes:
27+
- You can now `import`/`import()` markdown content directly using an ESM import.
28+
- A new `Astro.glob()` API, for easier glob imports (especially for Markdown).
29+
- **BREAKING CHANGE:** `Astro.fetchContent()` has been removed and replaced by `Astro.glob()`
30+
- **BREAKING CHANGE:** Markdown objects have an updated interface.
31+
32+
```diff
33+
// v0.25
34+
- let allPosts = Astro.fetchContent('./posts/*.md');
35+
// v0.26+
36+
+ let allPosts = await Astro.glob('./posts/*.md');
37+
```
38+
39+
When migrating, be careful about the new Markdown object interface. Frontmatter, for example, has been moved to the `.frontmatter` property, so references like `post.title` should change to `post.frontmatter.title`.
40+
41+
This should solve many issues for Markdown users, including some nice performance boosts for larger sites.
42+
43+
Read [RFC0017](https://github.com/withastro/rfcs/blob/main/proposals/0017-markdown-content-redesign.md) for more background on these changes.
44+
45+
### New Default Script Behavior
46+
47+
`<script>` tags in Astro components are now built, bundled and optimized by default. This completes a long-term move to make our Astro component syntax more consistent, matching the default-optimized behavior our `<style>` tags have today.
48+
49+
This includes a few changes to be aware of:
50+
51+
- **BREAKING:** `<script hoist>` is the new default `<script>` behavior. The `hoist` attribute has been removed.
52+
- New `<script is:inline>` directive, to revert a `<script>` tag to previous default behavior (unbuilt, unbundled, untouched by Astro).
53+
- New `<style is:inline>` directive, to leave a style tag inline in the page template (similar to previous `<script>` behavior).
54+
- New `<style is:global>` directive to replace `<style global>` in a future release.
55+
56+
57+
```diff
58+
// v0.25
59+
- <script hoist>
60+
// v0.26+
61+
+ <script>
62+
```
63+
64+
Read [RFC0016](https://github.com/withastro/rfcs/blob/main/proposals/0016-style-script-defaults.md) for more background on these changes.
65+
66+
### Updated Astro.request API
67+
68+
69+
`Astro.request` has been changed from our custom object to a standard `Request` object. This is part of a project to use more web standard APIs, especially where SSR is concerned.
70+
71+
This includes a few changes to be aware of:
72+
73+
- Change `Astro.request` to become a [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) object.
74+
- Move `Astro.request.params` to `Astro.params`.
75+
- Move `Astro.request.canonicalURL` to `Astro.canonicalURL`.
76+
77+
Read [RFC0018](https://github.com/withastro/rfcs/blob/main/proposals/0018-astro-request.md) for more background on these changes.
78+
79+
80+
### Other Changes
81+
82+
- Improve `Astro.slots` API to support passing arguments to function-based slots. This allows for more ergonomic utility components that accept a callback function as a child.
83+
- Update CLI output formatting, especially around error reporting.
84+
- Update `@astrojs/compiler`, fixing some bugs related to RegExp usage in frontmatter
85+
1186
## Migrate to v0.25
1287

1388
### Astro Integrations

0 commit comments

Comments
 (0)