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.

Sign up for GitHub

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

Add charset note md/mdx pages #9757

Merged
merged 5 commits into from
Oct 31, 2024
Merged

Add charset note md/mdx pages #9757

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3921e21
Add charset note md/mdx pages
bluwy Oct 21, 2024
40e162b
work changes throughout pages
sarah11918 Oct 23, 2024
3d3adb2
code indentation
sarah11918 Oct 23, 2024
6b1b9e8
fix spacing
sarah11918 Oct 23, 2024
51bffde
Merge branch '5.0.0-beta' into plt-1057-charset-utf-8
sarah11918 Oct 31, 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
25 changes: 19 additions & 6 deletions src/content/docs/en/basics/layouts.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,7 @@ const { title, description, publishDate, viewCount } = Astro.props;

Page layouts are especially useful for individual Markdown pages which otherwise would not have any page formatting.

Astro provides a special `layout` frontmatter property intended for [individual `.md` files located within `src/pages/` using file-based routing](/en/guides/markdown-content/#individual-markdown-pages) to specify which `.astro` component to use as the page layout. By default, this specified component can automatically access data from the Markdown file.
Astro provides a special `layout` frontmatter property intended for [individual `.md` files located within `src/pages/` using file-based routing](/en/guides/markdown-content/#individual-markdown-pages) to specify which `.astro` component to use as the page layout. This component allows you to provide `<head>` content like meta tags (e.g. `<meta charset="utf-8">`) and styles for the Markdown page. By default, this specified component can automatically access data from the Markdown file.

This is not recognized as a special property when using [content collections](/en/guides/content-collections/) to query and render your content.

Expand Down Expand Up @@ -132,6 +132,8 @@ const { frontmatter } = Astro.props;
<html>
<head>
<!-- Add other Head elements here, like styles and meta tags. -->
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta charset="utf-8">
<title>{frontmatter.title}</title>
</head>
<body>
Expand Down Expand Up @@ -163,6 +165,7 @@ const { frontmatter, url } = Astro.props;
---
<html>
<head>
<meta charset="utf-8">
<link rel="canonical" href={new URL(url, Astro.site).pathname}>
<title>{frontmatter.title}</title>
</head>
Expand Down Expand Up @@ -225,13 +228,23 @@ Then, your values are available to you through `Astro.props` in your layout, and
---
const { title, fancyJsHelper } = Astro.props;
---
<!-- -->
<h1>{title}</h1>
<slot /> <!-- your content is injected here -->
<p>{fancyJsHelper()}</p>
<!-- -->
<html>
<head>
<!-- -->
<meta charset="utf-8">
</head>
<body>
<!-- -->
<h1>{title}</h1>
<slot /> <!-- your content is injected here -->
<p>{fancyJsHelper()}</p>
<!-- -->
</body>
</html>
```

When using any layout (either through the frontmatter `layout` property or by importing a layout), you must include the `<meta charset="utf-8">` tag in your layout as Astro will no longer add it automatically to your MDX page.

<ReadMore>Learn more about Astro’s Markdown and MDX support in our [Markdown guide](/en/guides/markdown-content/).</ReadMore>

## Nesting Layouts
Expand Down
8 changes: 6 additions & 2 deletions src/content/docs/en/guides/markdown-content.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -450,7 +450,7 @@ const content = marked.parse(markdown);

Astro treats [any supported file inside of the `/src/pages/` directory](/en/basics/astro-pages/#supported-page-files) as a page, including `.md` and other Markdown file types.

Placing a file in this directory, or any sub-directory, will automatically build a page route using the pathname of the file and display the Markdown content rendered to HTML.
Placing a file in this directory, or any sub-directory, will automatically build a page route using the pathname of the file and display the Markdown content rendered to HTML. Astro will automatically add a `<meta charset="utf-8">` tag to your page to allow easier authoring of non-ASCII content.

```markdown title="src/pages/page-1.md"
---
Expand Down Expand Up @@ -492,6 +492,10 @@ This layout component is a regular Astro component with [specific properties aut
const {frontmatter} = Astro.props;
---
<html>
<head>
<!-- ... -->
<meta charset="utf-8"> // no longer added by default
</head>
<!-- ... -->
<h1>{frontmatter.title}</h1>
<h2>Post author: {frontmatter.author}</h2>
Expand All @@ -501,6 +505,6 @@ const {frontmatter} = Astro.props;
</html>
```

You can also [style your Markdown](/en/guides/styling/#markdown-styling) in your layout component.
When using the frontmatter `layout` property, you must include the `<meta charset="utf-8">` tag in your layout as Astro will no longer add it automatically. You can now also [style your Markdown](/en/guides/styling/#markdown-styling) in your layout component.

<ReadMore>Learn more about [Markdown Layouts](/en/basics/layouts/#markdown-layouts).</ReadMore>
16 changes: 16 additions & 0 deletions src/content/docs/en/guides/upgrade-to/v5.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -752,6 +752,22 @@ Code blocks in `.mdoc` files and Astro's built-in `<Code />` component do not us

<ReadMore>Read more about [syntax highlighting in Astro](/en/guides/markdown-content/#syntax-highlighting).</ReadMore>

### Changed: Automatic `charset=utf-8` behavior for Markdown and MDX pages
bluwy marked this conversation as resolved.
Show resolved Hide resolved

<SourcePR number="12231" title="Unset charset=utf-8 content-type for md/mdx pages"/>

In Astro 4.0, Markdown and MDX pages (located in `src/pages/`) automatically responded with `charset=utf-8` in the `Content-Type` header, which allowed rendering non-ASCII characters in your pages.

Astro 5.0 updates the behaviour to add the `<meta charset="utf-8">` tag instead, and only for pages that do not use Astro's special `layout` frontmatter property. Similarly for MDX pages, Astro will only add the tag if the MDX content does not import a wrapping `Layout` component.

If your Markdown or MDX pages use the `layout` frontmatter property, or if the MDX page content imports a wrapping `Layout` component, then the HTML encoding will be handled by the designated layout component instead, and the `<meta charset="utf-8">` tag will not be added to your page by default.

#### What should I do?

If you require `charset=utf-8` to render your page correctly, make sure that your layout components contain the `<meta charset="utf-8">` tag. You may need to add this if you have not already done so.

<ReadMore>Read more about [Markdown layouts](/en/basics/layouts/#markdown-layouts).</ReadMore>

### Changed: Astro-specific metadata attached in remark and rehype plugins

<SourcePR number="11861" title="Clean up Astro metadata in vfile.data"/>
Expand Down
Loading