Skip to content

Commit b585659

Browse files
ascorbicsarah11918delucisematipicoHiDeoo
authored
Astro 5.5 blog (#1429)
* Astro 5.5 blog * Update * Apply suggestions from code review Co-authored-by: Sarah Rainsberger <[email protected]> Co-authored-by: Chris Swithinbank <[email protected]> * Add script order flag * Apply suggestions from code review Co-authored-by: Sarah Rainsberger <[email protected]> * Rewording, links * Credits * Update src/content/blog/astro-550.mdx Co-authored-by: Emanuele Stoppa <[email protected]> * Apply suggestions from code review Co-authored-by: HiDeoo <[email protected]> * added docs links --------- Co-authored-by: Sarah Rainsberger <[email protected]> Co-authored-by: Chris Swithinbank <[email protected]> Co-authored-by: Emanuele Stoppa <[email protected]> Co-authored-by: HiDeoo <[email protected]>
1 parent 4b4b68a commit b585659

File tree

3 files changed

+168
-0
lines changed

3 files changed

+168
-0
lines changed

‎src/content/blog/_images/astro-550/blog-post-5-5.webp

57.2 KB
Binary file not shown.

‎src/content/blog/_images/astro-550/og-astro-5-5.webp

48.8 KB
Binary file not shown.

‎src/content/blog/astro-550.mdx

+168
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
---
2+
title: 'Astro 5.5'
3+
description: 'Astro 5.5 dives deep with better support for diagramming tools, improved Markdown compatibility, and type-safe sessions!'
4+
homepageLink:
5+
title: 'Astro 5.5'
6+
subtitle: 'Available now!'
7+
publishDate: '2025-03-13'
8+
authors:
9+
- matt
10+
coverImage: '/src/content/blog/_images/astro-550/blog-post-5-5.webp'
11+
socialImage: '/src/content/blog/_images/astro-550/og-astro-5-5.webp'
12+
lang: 'en'
13+
---
14+
15+
import BlogContentImage from '/src/components/BlogContentImage.astro';
16+
17+
**Astro 5.5 dives deep with better support for diagramming tools, improved Markdown compatibility, and type-safe sessions!**
18+
19+
🧜‍♀️ Dive into a sea of new features with these improvements to Astro:
20+
21+
- [**Better support for diagramming tools in Markdown**](#better-support-for-diagramming-tools-in-markdown)
22+
- [**Type-safe experimental sessions**](#type-safe-experimental-sessions)
23+
- [**Improved heading ID compatibility**](#improved-heading-id-compatibility)
24+
- [**Experimental: preserve order of style and script tags**](#experimental-preserve-order-of-style-and-script-tags)
25+
26+
To upgrade an existing project, use the automated `@astrojs/upgrade` CLI tool. Alternatively, upgrade manually by running the upgrade command for your package manager:
27+
28+
```sh
29+
# Recommended:
30+
npx @astrojs/upgrade
31+
32+
# Manual:
33+
npm install astro@latest
34+
pnpm upgrade astro --latest
35+
yarn upgrade astro --latest
36+
```
37+
38+
## Better support for diagramming tools in Markdown
39+
40+
Tools like Mermaid and D2 let you define charts and diagrams in code blocks in Markdown, which are then rendered inside the content. Until now, using these in Astro could be tricky, because Astro's default syntax highlighting would interfere with how the code blocks were rendered.
41+
42+
Astro 5.5 introduces a new [`excludeLangs`](https://docs.astro.build/en/reference/configuration-reference/#markdownsyntaxhighlightexcludelangs) option in your Markdown configuration that makes it possible to skip syntax highlighting for specific language code blocks. This unlocks the ability to use tools like these without disabling syntax highlighting for other blocks.
43+
44+
Here's an example of how to configure Astro to disable highlighting for the `mermaid` language after installing the [`rehype-mermaid` plugin](https://github.com/remcohaszing/rehype-mermaid):
45+
46+
```js title="astro.config.mjs"
47+
import { defineConfig } from 'astro/config';
48+
import rehypeMermaid from 'rehype-mermaid';
49+
50+
export default defineConfig({
51+
markdown: {
52+
syntaxHighlight: {
53+
type: 'shiki',
54+
excludeLangs: ['mermaid', 'math'],
55+
},
56+
rehypePlugins: [rehypeMermaid],
57+
},
58+
});
59+
```
60+
61+
Then, you can create diagrams directly in your Markdown content:
62+
63+
````md
64+
```mermaid
65+
graph TD
66+
A[Start] --> B{Is it working?}
67+
B -->|Yes| C[Great!]
68+
B -->|No| D[Debug]
69+
D --> B
70+
```
71+
````
72+
73+
This will then render as a diagram in your page.
74+
75+
Massive thanks to [Chris Chua](https://github.com/chrisirhc) for this contribution.
76+
77+
## Type-safe experimental sessions
78+
79+
Astro 5.5 adds support for proper TypeScript typing for your session data, letting you banish `any` mistakes. Experimental support for session storage was added in Astro 5.1, but previously all session data was untyped. Now you can define the types of your session data by extending the global `App.SessionData` interface in your project's `src/env.d.ts` file:
80+
81+
```ts title="src/env.d.ts"
82+
declare namespace App {
83+
interface SessionData {
84+
user: {
85+
id: string;
86+
email: string;
87+
};
88+
lastLogin: Date;
89+
}
90+
}
91+
```
92+
93+
This is optional, and any keys not defined in this interface will be treated as `any`. However, defining the types will provide accurate type checking and autocomplete when working with session data in your site:
94+
95+
```astro
96+
---
97+
const user = await Astro.session.get('user');
98+
// `user` is properly typed as `{ id: string; email: string; } | undefined`
99+
100+
const something = await Astro.session.get('something');
101+
// `something` is typed as `any` since it's not defined in the interface
102+
103+
// TypeScript will catch this error:
104+
Astro.session.set('user', 1); // Error: Type 'number' is not assignable to type '{ id: string; email: string; }'
105+
---
106+
```
107+
108+
This improvement makes working with sessions in Astro more reliable and helps catch potential errors at development time rather than at runtime.
109+
110+
For more information, see the [experimental sessions docs](https://docs.astro.build/en/reference/experimental-flags/sessions/#session-data-types).
111+
112+
## Improved heading ID compatibility
113+
114+
Astro 5.5 introduces a new [`experimental.headingIdCompat`](https://docs.astro.build/en/reference/experimental-flags/heading-id-compat/) flag that generates heading IDs consistent with other common Markdown processors like those used by GitHub and npm.
115+
116+
By default, Astro removes trailing dashes from the end of IDs it generates for headings containing special characters. This behavior differs from other common Markdown processors, which can cause inconsistencies when linking to headings across different platforms.
117+
118+
With the new configuration flag, you can now ensure your heading IDs follow the same convention as other platforms:
119+
120+
```js title="astro.config.mjs"
121+
import { defineConfig } from 'astro/config';
122+
123+
export default defineConfig({
124+
experimental: {
125+
headingIdCompat: true,
126+
},
127+
});
128+
```
129+
130+
This is particularly useful for sites that might have anchor links shared between GitHub, npm documentation, and your Astro website.
131+
132+
## Experimental: preserve order of style and script tags
133+
134+
Experimental flags aren't only for cool new features. Sometimes, things just have to *change*. We also use experimental flags to carefully introduce you to breaking changes that will eventually become the new default behavior. [`experimental.preserveScriptOrder`](https://docs.astro.build/en/reference/experimental-flags/preserve-scripts-order/) is one of them!
135+
136+
When rendering multiple `<style>` and `<script>` tags on the same page, Astro currently reverses their order in your generated HTML output. This can give unexpected results, for example CSS styles that apply in development mode being overridden by earlier style tags once your site is built.
137+
138+
You can enable it in your configuration like this:
139+
140+
```js title="astro.config.mjs"
141+
import { defineConfig } from 'astro/config';
142+
143+
export default defineConfig({
144+
experimental: {
145+
preserveScriptOrder: true,
146+
},
147+
});
148+
```
149+
150+
With the new `preserveScriptOrder` flag set to `true`, Astro will generate your styles and scripts in the order they are defined. If you were previously compensating for Astro's behavior by writing these out of order, you will need to update your code.
151+
152+
We think this change makes sense in the long run for everyone, so we encourage you to test this now to ensure it works before it becomes the default behavior.
153+
154+
Thanks to [JaneSmith](https://github.com/withastro/astro/issues/12264) for first identifying this issue, and [Reuben Tier](https://github.com/TheOtterLord) for contributing the compiler fix!
155+
156+
## Bug fixes
157+
158+
As always, we've been working hard on fixing issues since the [5.4 release](/blog/astro-540). See [the changelog](https://github.com/withastro/astro/blob/main/packages/astro/CHANGELOG.md) for all the details.
159+
160+
## Thanks
161+
162+
Thanks to everyone who contributed to this release, including [Chris Swithinbank](https://github.com/delucis), [Emanuele Stoppa](https://github.com/ematipico), [Reuben Tier](https://github.com/TheOtterLord), [Luiz Ferraz](https://github.com/Fryuni), [Sarah Rainsberger](https://github.com/sarah11918), [HiDeoo](https://github.com/HiDeoo), [HappyDev](https://github.com/MoustaphaDev), [Yan Thomas](https://github.com/yanthomasdev), [Bjorn Lu](https://github.com/bluwy), [Chris Chua](https://github.com/chrisirhc), and many more.
163+
164+
We look forward to seeing what you build with Astro 5.5! If you have questions, comments, or just want to say hi, drop by the [Astro Discord](https://astro.build/chat).
165+
166+
import RelatedPosts from './_components/RelatedPosts.astro';
167+
168+
<RelatedPosts slugs={['astro-540', 'astro-530']} />

0 commit comments

Comments
 (0)