diff --git a/src/pages/en/core-concepts/astro-pages.mdx b/src/pages/en/core-concepts/astro-pages.mdx index 5776cdaf80fde..9d0377aa5ec09 100644 --- a/src/pages/en/core-concepts/astro-pages.mdx +++ b/src/pages/en/core-concepts/astro-pages.mdx @@ -20,6 +20,8 @@ Astro supports the following file types in the `src/pages/` directory: 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. +A single file can also generate multiple pages using [dynamic routing](/en/core-concepts/routing/#dynamic-routes). This allows you to create pages even if your content lives outside of the special `/pages/` directory, such as in a [content collection](/en/guides/content-collections/#rendering-entry-content) or a [CMS](/en/guides/cms/). + 📚 Read more about [Routing in Astro](/en/core-concepts/routing/). ### Link between pages @@ -62,6 +64,8 @@ import MySiteLayout from '../layouts/MySiteLayout.astro'; 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. +[Collections of Markdown or MDX page content](/en/guides/content-collections/) in `src/content/` can be used to [generate pages dynamically](/en/core-concepts/routing/#dynamic-routes). + 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 `...` page document. ```md {3} diff --git a/src/pages/en/guides/markdown-content.mdx b/src/pages/en/guides/markdown-content.mdx index 78229e0ad795b..c2e56b5b5519a 100644 --- a/src/pages/en/guides/markdown-content.mdx +++ b/src/pages/en/guides/markdown-content.mdx @@ -6,6 +6,7 @@ i18nReady: true --- import Since from '~/components/Since.astro' +import FileTree from '~/components/FileTree.astro' [Markdown](https://daringfireball.net/projects/markdown/) is commonly used to author text-heavy content like blog posts and documentation. Astro includes built-in support for standard Markdown files. @@ -15,6 +16,25 @@ Use either or both types of files to write your Markdown content! ## Markdown and MDX Pages +### Content collections + +You can manage your Markdown and MDX files in Astro in a special `src/content/` folder. [Content collections](/en/guides/content-collections/) help you organize your content, validate your frontmatter, and provide automatic TypeScript type-safety while working with your content. + + +- src/content/ + - **newsletter/** + - week-1.md + - week-2.md + - **authors/** + - grace-hopper.md + - alan-turing.md + + + + +See more about using [content collections in Astro](/en/guides/content-collections/). + + ### File-based Routing Astro treats any `.md` (or alternative supported extension) or `.mdx` file inside of the `/src/pages/` directory as a page. @@ -131,6 +151,9 @@ const {frontmatter} = Astro.props; ``` +You can also [style your Markdown](/en/guides/styling/#markdown-styling) in your layout component. + + 📚 Learn more about [Markdown Layouts](/en/core-concepts/layouts/#markdownmdx-layouts). @@ -151,7 +174,6 @@ I can link internally to [my conclusion](#conclusion) on the same page when writ I can use the URL `https://my-domain.com/page-1/#introduction` to navigate directly to my Introduction on the page. ``` - ### Escaping special characters Certain characters have a special meaning in Markdown and MDX. You may need to use a different syntax if you want to display them. To do this, you can use [HTML entities](https://developer.mozilla.org/en-US/docs/Glossary/Entity) for these characters instead. @@ -428,7 +450,7 @@ You can customize how remark parses your Markdown in `astro.config.mjs`. See the ### Markdown Plugins -Astro supports adding third-party [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) plugins for Markdown and MDX. These plugins allow you to extend your Markdown with new capabilities, like [auto-generating a table of contents](https://github.com/remarkjs/remark-toc), [applying accessible emoji labels](https://github.com/florianeckerstorfer/remark-a11y-emoji), and more. +Astro supports adding third-party [remark](https://github.com/remarkjs/remark) and [rehype](https://github.com/rehypejs/rehype) plugins for Markdown and MDX. These plugins allow you to extend your Markdown with new capabilities, like [auto-generating a table of contents](https://github.com/remarkjs/remark-toc), [applying accessible emoji labels](https://github.com/florianeckerstorfer/remark-a11y-emoji), and [styling your Markdown](/en/guides/styling/#markdown-styling). We encourage you to browse [awesome-remark](https://github.com/remarkjs/awesome-remark) and [awesome-rehype](https://github.com/rehypejs/awesome-rehype) for popular plugins! See each plugin's own README for specific installation instructions. diff --git a/src/pages/en/guides/styling.mdx b/src/pages/en/guides/styling.mdx index a0f0987c5bc97..e2c40b1b1fce7 100644 --- a/src/pages/en/guides/styling.mdx +++ b/src/pages/en/guides/styling.mdx @@ -481,6 +481,13 @@ Vue in Astro supports the same methods as `vue-loader` does: Svelte in Astro also works exactly as expected: [Svelte Styling Docs][svelte-style]. +## Markdown Styling + +Any Astro styling methods are available to a [Markdown layout component](/en/core-concepts/layouts/#markdownmdx-layouts). + +You can apply global styles to your Markdown content by adding [`