withastro · Jutanium · Sep 13, 2022 · Sep 12, 2022 · Sep 12, 2022 · Sep 12, 2022
diff --git a/src/pages/en/core-concepts/astro-components.md b/src/pages/en/core-concepts/astro-components.md
@@ -492,6 +492,18 @@ Astro detects these JavaScript client-side imports and then builds, optimizes, a
 </script>
 ```
 
+## HTML Components
+
+Astro supports importing and using `.html` files as components or placing these files within the `src/pages` subdirectory as pages. You may want to use HTML components if you're reusing code from an existing site built without a framework, or if you want to ensure that your component has no dynamic features.
+
+HTML components must contain only valid HTML, and therefore lack key Astro component features:
+- They don't support frontmatter, server-side imports, or dynamic expressions.
+- Any `<script>` tags are left unbundled, treated as if they had `is:inline`. 
+- They can only [reference assets that are in the `public/` folder](/en/guides/images/#public).
+
+:::note
+A [`<slot />` element](/en/core-concepts/astro-components/#slots) inside an HTML component will work as it would in an Astro component. In order to use the [HTML Web Component Slot](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/slot) element instead, add `is:inline` to your `<slot>` element.
+:::
 
 ## Next Steps
 

diff --git a/src/pages/en/core-concepts/astro-pages.md b/src/pages/en/core-concepts/astro-pages.md
@@ -5,20 +5,28 @@ description: An introduction to Astro pages
 i18nReady: true
 ---
 
-**Pages** are a special type of [Astro component](/en/core-concepts/astro-components/) that live in the `src/pages/` subdirectory. They are responsible for handling routing, data loading, and overall page layout for every HTML page in your website.
+**Pages** are files that live in the `src/pages/` subdirectory of your Astro project. They are responsible for handling routing, data loading, and overall page layout for every page in your website.
 
-### File-based routing
+## Supported page files 
 
-Astro leverages a routing strategy called **file-based routing.** Every `.astro` file in your `src/pages` directory becomes a page or an endpoint on your site based on its file path.
+Astro supports the following file types in the `src/pages/` directory:
+- [`.astro`](#astro-pages)
+- [`.md`](#markdownmdx-pages)
+- `.mdx` (with the [MDX Integration installed](/en/guides/integrations-guide/mdx/#installation))
+- [`.js`/`.ts`](#file-routes)
+- [`.html`](#html-pages)
 
-Write standard HTML [`<a>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) in your component template to link between pages.
+## File-based routing
+
+Astro leverages a routing strategy called **file-based routing**. Each file in your `src/pages/` directory becomes an endpoint on your site based on its file path.
 
+Write standard HTML [`<a>` elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a) in your component template to link between pages.
 
 📚 Read more about [Routing in Astro](/en/core-concepts/routing/).
 
-### Page HTML
+## Astro Pages
 
-Astro Pages must return a full `<html>...</html>` page response, including `<head>` and `<body>`. (`<!doctype html>` is optional, and will be added automatically.)
+Astro pages use the `.astro` file extension and support the same features as [Astro components](/en/core-concepts/astro-components/).
 
 ```astro
 ---
@@ -34,8 +42,6 @@ Astro Pages must return a full `<html>...</html>` page response, including `<hea
 </html>
 ```
 
-### Leveraging Page Layouts
-
 To avoid repeating the same HTML elements on every page, you can move common `<head>` and `<body>` elements into your own [layout components](/en/core-concepts/layouts/). You can use as many or as few layout components as you'd like.
 
 ```astro {3} /</?MySiteLayout>/
@@ -50,17 +56,11 @@ import MySiteLayout from '../layouts/MySiteLayout.astro';
 
 📚 Read more about [layout components](/en/core-concepts/layouts/) in Astro.
 
-#### Modifying `<head>`
-
-Note that using a `<head>` tag works like any other HTML tag: it does not get moved to the top of the page. We recommend writing `<head>` and its contents in your top-level layout.
-
+## Markdown/MDX Pages
 
+Astro also treats any Markdown (`.md`) files inside of `src/pages/` as pages in your final website. If you have the [MDX Integration installed](/en/guides/integrations-guide/mdx/#installation), it also treats MDX (`.mdx`) files the same way. These are commonly used for text-heavy pages like blog posts and documentation.
 
-## Markdown Pages
-
-Astro also treats any Markdown (`.md`) files inside of `/src/pages/` as pages in your final website. These are commonly used for text-heavy pages like blog posts and documentation.
-
-Page layouts are especially useful for [Markdown files.](#markdown-pages) Markdown files can use the special `layout` front matter property to specify a [layout component](/en/core-concepts/layouts/) that will wrap their Markdown content in a full `<html>...</html>` page document.
+Page layouts are especially useful for [Markdown files](#markdownmdx-pages). Markdown files can use the special `layout` front matter property to specify a [layout component](/en/core-concepts/layouts/) that will wrap their Markdown content in a full `<html>...</html>` page document.
 
 ```md {3}
 ---
@@ -76,15 +76,11 @@ This is my page, written in **Markdown.**
 📚 Read more about [Markdown](/en/guides/markdown-content/) in Astro.
 
 
-## Non-HTML Pages
-
-Non-HTML pages, like `.json` or `.xml`, or even assets such as images, can be built using API routes commonly referred to as **File Routes**.
+## File Routes
 
-**File Routes** are script files that end with the `.js` or `.ts` extension and are located within the `src/pages/` directory.
+**File Routes** are script files that end with the `.js` or `.ts` extension and are located within the `src/pages/` directory. These can build non-HTML pages, like .json or .xml, or even assets such as images.
 
-Built filenames and extensions are based on the source file's name, ex: `src/pages/data.json.ts` will be built to match the `/data.json` route in your final build.
-
-In SSR (server-side rendering) the extension does not matter and can be omitted. This is because no files are generated at build time. Instead, Astro generates a single server file.
+The `.js` or `.ts` extension will be removed during the build process. For example, `src/pages/data.json.ts` will be built to match the `/data.json` route. 
 
 ```js
 // Example: src/pages/builtwith.json.ts
@@ -102,7 +98,7 @@ export async function get() {
 }
 ```
 
-API Routes receive an `APIContext` object which contains [params](/en/reference/api-reference/#params) and a [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request):
+As API Routes, File Routes receive an `APIContext` object which contains [params](/en/reference/api-reference/#params) and a [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request):
 
 ```ts title="src/pages/request-path.json.ts"
 import type { APIContext } from 'astro';
@@ -145,6 +141,10 @@ export const get: APIRoute = ({ params, request }) => {
 
 ```
 
+## HTML Pages
+
+Files with the `.html` file extension can be placed in the `src/pages/` and used directly as pages on your site. Note that some key Astro features are not supported in [HTML Components](/en/core-concepts/astro-components/#html-components).
+
 ## Custom 404 Error Page
 
 For a custom 404 error page, you can create a `404.astro` or `404.md` file in `/src/pages`.

diff --git a/src/pages/en/guides/markdown-content.md b/src/pages/en/guides/markdown-content.md
@@ -585,7 +585,7 @@ When using Prism, you'll need to add a stylesheet to your project for syntax hig
 1. [Setting `syntaxHighlight: 'prism'`](#choose-a-syntax-highlighter) from your `@astrojs/markdown-remark` config.
 1. Choosing a premade stylesheet from the available [Prism Themes](https://github.com/PrismJS/prism-themes).
 2. Adding this stylesheet to [your project's `public/` directory](/en/core-concepts/project-structure/#public).
-3. Loading this [into your page's `<head>`](/en/core-concepts/astro-pages/#page-html) via a `<link>` tag.
+3. Loading this [into your page's `<head>`](/en/guides/troubleshooting/#using-head-in-a-component) via a `<link>` tag.
 
 You can also visit the [list of languages supported by Prism](https://prismjs.com/#supported-languages) for options and usage.
 

diff --git a/src/pages/en/guides/rss.md b/src/pages/en/guides/rss.md
@@ -10,7 +10,7 @@ Astro supports fast, automatic RSS feed generation for blogs and other content w
 
 ## Setting up `@astrojs/rss`
 
-The `@astrojs/rss` package provides helpers for generating RSS feeds using [API endpoints](/en/core-concepts/astro-pages/#non-html-pages). This unlocks both static builds _and_ on-demand generation when using an [SSR adapter](/en/guides/server-side-rendering/#enabling-ssr-in-your-project).
+The `@astrojs/rss` package provides helpers for generating RSS feeds using [API endpoints](/en/core-concepts/astro-pages/#file-routes). This unlocks both static builds _and_ on-demand generation when using an [SSR adapter](/en/guides/server-side-rendering/#enabling-ssr-in-your-project).
 
 First, install `@astrojs/rss` using your preferred package manager:
 

diff --git a/src/pages/en/guides/troubleshooting.md b/src/pages/en/guides/troubleshooting.md
@@ -127,6 +127,10 @@ Yarn 2+, a.k.a. Berry, uses a technique called [Plug'n'Play (PnP)](https://yarnp
 nodeLinker: "node-modules"
 ```
 
+### Using `<head>` in a component
+
+In Astro, using a `<head>` tag works like any other HTML tag: it does not get moved to the top of the page or merged with the existing `<head>`. Because of this, you usually only want to include one `<head>` tag throughout a page. We recommend writing that single `<head>` and its contents in a [layout component](/en/core-concepts/layouts/).
+
 ## Tips and tricks
 
 ### Debugging with `console.log()`

diff --git a/src/pages/en/reference/integrations-reference.md b/src/pages/en/reference/integrations-reference.md
@@ -119,7 +119,7 @@ A callback function to add a component framework renderer (i.e. React, Vue, Svel
 
 **Type:** `({ pattern: string, entryPoint: string }) => void;`
 
-A callback function to inject routes into an Astro project. Injected routes can be [`.astro` pages](/en/core-concepts/astro-pages/) or [`.js` and `.ts` route handlers](/en/core-concepts/astro-pages/#non-html-pages).
+A callback function to inject routes into an Astro project. Injected routes can be [`.astro` pages](/en/core-concepts/astro-pages/) or [`.js` and `.ts` route handlers](/en/core-concepts/astro-pages/#file-routes).
 
 `injectRoute` takes an object with a `pattern` and an `entryPoint`.