michael/astro
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

[DOCS] Add more information about content.astro (markdown) (#1148)

Browse source 
* Correct heading levels

* Add more info about content.astro

* Remove accidental heading
This commit is contained in:
Marcus Otterström 2021-08-19 01:45:35 +02:00 committed by GitHub
parent 52cf927564
commit b5e5dcfed0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 43 additions and 40 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

83
docs/src/pages/guides/markdown-content.md
View file

@ -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 `<slot />` 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 `<slot />` element.
`src/layouts/main.astro`
```jsx
// src/layouts/BaseLayout.astro
---
const { content } = Astro.props;
---
<html>
<head>
<title>{content.title}</title>
</head>
<body>
<slot/>
<slot />
</body>
</html>
```
### 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 `<Markdown>` component, within your frontmatter block use the following import statement:
@ -176,7 +179,7 @@ const expressions = 'Lorem ipsum';
</Layout>
````
### 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
</Layout>
```
### Security FAQs
## Security FAQs
**Aren't there security concerns to rendering remote markdown directly to HTML?**