Major Changes
-
#5687
e2019be6f
Thanks @bholmesdev! - Give remark and rehype plugins access to user frontmatter via frontmatter injection. This meansdata.astro.frontmatter
is now the complete Markdown or MDX document's frontmatter, rather than an empty object.This allows plugin authors to modify existing frontmatter, or compute new properties based on other properties. For example, say you want to compute a full image URL based on an
imageSrc
slug in your document frontmatter:export function remarkInjectSocialImagePlugin() { return function (tree, file) { const { frontmatter } = file.data.astro; frontmatter.socialImageSrc = new URL(frontmatter.imageSrc, 'https://my-blog.com/').pathname; }; }
Content Collections - new
remarkPluginFrontmatter
propertyWe have changed inject frontmatter to modify frontmatter in our docs to improve discoverability. This is based on support forum feedback, where "injection" is rarely the term used.
To reflect this, the
injectedFrontmatter
property has been renamed toremarkPluginFrontmatter
. This should clarify this plugin is still separate from thedata
export Content Collections expose today.Migration instructions
Plugin authors should now check for user frontmatter when applying defaults.
For example, say a remark plugin wants to apply a default
title
if none is present. Add a conditional to check if the property is present, and update if none exists:export function remarkInjectTitlePlugin() { return function (tree, file) { const { frontmatter } = file.data.astro; + if (!frontmatter.title) { frontmatter.title = 'Default title'; + } } }
This differs from previous behavior, where a Markdown file's frontmatter would always override frontmatter injected via remark or reype.
-
#5728
8fb28648f
Thanks @natemoo-re! - The previously experimental features--experimental-error-overlay
and--experimental-prerender
, both added in v1.7.0, are now the default.You'll notice that the error overlay during
astro dev
has a refreshed visual design and provides more context for your errors.The
prerender
feature is now enabled by default when usingoutput: 'server'
. To prerender a particular page, addexport const prerender = true
to your frontmatter.Warning
Integration authors that previously relied on the exact structure of Astro's v1.0 build output may notice some changes to our output file structure. Please test your integrations to ensure compatability.
Users that have configured a customvite.build.rollupOptions.output.chunkFileNames
should ensure that their Astro project is configured as an ESM Node project. Either include"type": "module"
in your rootpackage.json
file or use the.mjs
extension forchunkFileNames
. -
#5716
dd56c1941
Thanks @bluwy! - Remove MDX Fragment hack. This was used by@astrojs/mdx
to access theFragment
component, but isn't require anymore since@astrojs/mdx
v0.12.1. -
#5685
f6cf92b48
Thanks @bluwy! - Upgrade to Vite 4. Please see its migration guide for more information. -
#5724
16c7d0bfd
Thanks @bluwy! - Remove outdated Vue info log. RemovetoString
support forRenderTemplateResult
. -
#5684
a9c292026
Thanks @bholmesdev! - Refine Markdown and MDX configuration options for ease-of-use.Markdown
- Remove
remark-smartypants
from Astro's default Markdown plugins. - Replace the
extendDefaultPlugins
option with a simplifiedgfm
boolean. This is enabled by default, and can be disabled to remove GitHub-Flavored Markdown. - Ensure GitHub-Flavored Markdown is applied whether or not custom
remarkPlugins
orrehypePlugins
are configured. If you want to apply custom plugins and remove GFM, manually setgfm: false
in your config.
MDX
- Support all Markdown configuration options (except
drafts
) from your MDX integration config. This includessyntaxHighlighting
andshikiConfig
options to further customize the MDX renderer. - Simplify
extendDefaults
to anextendMarkdownConfig
option. MDX options will default to their equivalent in your Markdown config. By settingextendMarkdownConfig
to false, you can "eject" to set your own syntax highlighting, plugins, and more.
Migration
To preserve your existing Markdown and MDX setup, you may need some configuration changes:
Smartypants manual installation
Smartypants has been removed from Astro's default setup. If you rely on this plugin, install
remark-smartypants
and apply to yourastro.config.*
:// astro.config.mjs import { defineConfig } from 'astro/config'; + import smartypants from 'remark-smartypants'; export default defineConfig({ markdown: { + remarkPlugins: [smartypants], } });
Migrate
extendDefaultPlugins
togfm
You may have disabled Astro's built-in plugins (GitHub-Flavored Markdown and Smartypants) with the
extendDefaultPlugins
option. Since Smartypants has been removed, this has been renamed togfm
.// astro.config.mjs import { defineConfig } from 'astro/config'; export default defineConfig({ markdown: { - extendDefaultPlugins: false, + gfm: false, } });
Additionally, applying remark and rehype plugins no longer disables
gfm
. You will need to opt-out manually by settinggfm
tofalse
.Migrate MDX's
extendPlugins
toextendMarkdownConfig
You may have used the
extendPlugins
option to manage plugin defaults in MDX. This has been replaced by 2 flags:extendMarkdownConfig
(true
by default) to toggle Markdown config inheritance. This replaces theextendPlugins: 'markdown'
option.gfm
(true
by default) to toggle GitHub-Flavored Markdown in MDX. This replaces theextendPlugins: 'defaults'
option.
- Remove
-
#5707
5eba34fcc
Thanks @bluwy! - Remove deprecatedAstro
global APIs, includingAstro.resolve
,Astro.fetchContent
, andAstro.canonicalURL
.Astro.resolve
You can resolve asset paths using
import
instead. For example:--- import 'style.css'; import imageUrl from './image.png'; --- <img src={imageUrl} />
See the v0.25 migration guide for more information.
Astro.fetchContent
Use
Astro.glob
instead to fetch markdown files, or migrate to the Content Collections feature.let allPosts = await Astro.glob('./posts/*.md');
Astro.canonicalURL
Use
Astro.url
instead to construct the canonical URL.const canonicalURL = new URL(Astro.url.pathname, Astro.site);
-
#5707
5eba34fcc
Thanks @bluwy! - RemovebuildConfig
option parameter from integrationastro:build:start
hook in favour of thebuild.config
option in theastro:config:setup
hook.export default function myIntegration() { return { name: 'my-integration', hooks: { 'astro:config:setup': ({ updateConfig }) => { updateConfig({ build: { client: '...', server: '...', serverEntry: '...', }, }); }, }, }; }