From b5e5dcfed009a6db0c087c115679bcf587da7cdf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marcus=20Otterstr=C3=B6m?=
<35617441+MarcusOtter@users.noreply.github.com>
Date: Thu, 19 Aug 2021 01:45:35 +0200
Subject: [PATCH] [DOCS] Add more information about content.astro (markdown)
(#1148)
* Correct heading levels
* Add more info about content.astro
* Remove accidental heading
---
docs/src/pages/guides/markdown-content.md | 83 ++++++++++++-----------
1 file changed, 43 insertions(+), 40 deletions(-)
diff --git a/docs/src/pages/guides/markdown-content.md b/docs/src/pages/guides/markdown-content.md
index 220a7ea16..5286db44b 100644
--- a/docs/src/pages/guides/markdown-content.md
+++ b/docs/src/pages/guides/markdown-content.md
@@ -13,7 +13,7 @@ Also, Astro supports third-party plugins for Markdown. You can provide your plug
> **Note:** Enabling custom `remarkPlugins` or `rehypePlugins` removes Astro's built-in support for [GitHub-flavored Markdown](https://github.github.com/gfm/) support, [Footnotes](https://github.com/remarkjs/remark-footnotes) syntax, [Smartypants](https://github.com/silvenon/remark-smartypants), [Remark-slug](https://github.com/remarkjs/remark-slug). You must explicitly add these plugins to your `astro.config.mjs` file, if desired.
-## Add a Markdown plugin in Astro
+### Add a Markdown plugin in Astro
If you want to add a plugin, you need to install the npm package dependency in your project and then update the `markdownOptions.remarkPlugins` or `markdownOptions.rehypePlugins` depends on what plugin you want to have:
@@ -49,65 +49,68 @@ export default {
};
```
-### Markdown Pages
+## Markdown Pages
-Astro treats any `.md` files inside of the `/src/pages` directory as pages. These pages are processed as plain markdown files and do not support components. If you're looking to embed rich components in your markdown, take a look at the [Markdown Component](#astros-markdown-component) section.
-
-`layout`
-
-The only special Frontmatter key is `layout`, which defines the relative path to an `.astro` component which should wrap your Markdown content.
-
-`src/pages/index.md`
+Astro treats any `.md` files inside of the `/src/pages` directory as pages. These files can contain frontmatter, but are otherwise processed as plain markdown files and do not support components. If you're looking to embed rich components in your markdown, take a look at the [Markdown Component](#astros-markdown-component) section.
+### Layouts
+Markdown pages have a special frontmatter property for `layout`. This defines the relative path to an `.astro` component which should wrap your Markdown content, for example a [Layout](/core-concepts/layouts) component. All other frontmatter properties defined in your `.md` page will be exposed to the component as properties of the `content` prop. The rendered Markdown content is placed into the default `` element.
```jsx
+// src/pages/index.md
---
-layout: ../layouts/main.astro
+layout: ../../layouts/BaseLayout.astro
+title: My cool page
---
# Hello World!
```
-
-Layout files are normal `.astro` components. Any Frontmatter defined in your `.md` page will be exposed to the Layout component as the `content` prop. `content` also has an `astro` key which holds special metadata about your file, like the complete Markdown `source` and a `headings` object.
-
-Keep in mind that the only guaranteed variables coming from the `content` prop object are `astro` and `url`. An example of what a blog post `content` object might look like is as follows:
-
-```json
-{
- /** Frontmatter from blog post
- "title": "",
- "date": "",
- "author": "",
- "description": "",
- **/
- "astro": {
- "headers": [],
- "source": ""
- },
- "url": ""
-}
-```
-
-The rendered Markdown content is placed into the default `` element.
-
-`src/layouts/main.astro`
-
```jsx
+// src/layouts/BaseLayout.astro
---
const { content } = Astro.props;
---
-
{content.title}
-
+
```
-### Astro's Markdown Component
+For Markdown files, the `content` prop also has an `astro` property which holds special metadata about the page such as the complete Markdown `source` and a `headers` object. An example of what a blog post `content` object might look like is as follows:
+```json
+{
+ /** Frontmatter from a blog post
+ "title": "Astro 0.18 Release",
+ "date": "Tuesday, July 27 2021",
+ "author": "Matthew Phillips",
+ "description": "Astro 0.18 is our biggest release since Astro launch.",
+ **/
+ "astro": {
+ "headers": [
+ {
+ "depth": 1,
+ "text": "Astro 0.18 Release",
+ "slug": "astro-018-release"
+ },
+ {
+ "depth": 2,
+ "text": "Responsive partial hydration",
+ "slug": "responsive-partial-hydration"
+ },
+ /* ... */
+ ],
+ "source": "# Astro 0.18 Release\\nA little over a month ago, the first public beta [...]"
+ },
+ "url": ""
+}
+```
+> Keep in mind that the only guaranteed properties coming from the `content` prop are `astro` and `url`.
+
+## Astro's Markdown Component
Astro has a dedicated component used to let you render your markdown as HTML components. This is a special component that is only exposed to `.astro` files. To use the `` component, within your frontmatter block use the following import statement:
@@ -176,7 +179,7 @@ const expressions = 'Lorem ipsum';
````
-### Remote Markdown
+## Remote Markdown
If you have Markdown in a remote source, you may pass it directly to the Markdown component through the `content` attribute. For example, the example below fetches the README from Snowpack's GitHub repository and renders it as HTML.
@@ -212,7 +215,7 @@ const content = await fetch('https://raw.githubusercontent.com/snowpackjs/snowpa
```
-### Security FAQs
+## Security FAQs
**Aren't there security concerns to rendering remote markdown directly to HTML?**