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

Remove references to the <Markdown> component #1045

Merged
merged 8 commits into from
Jul 26, 2022
Merged

Remove references to the <Markdown> component #1045

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
aab6122
Remove references to the <Markdown> component
matthewp Jul 20, 2022
c3130a0
Fix links
matthewp Jul 20, 2022
cef7127
Merge branch 'main' into remove-markdown
sarah11918 Jul 22, 2022
9924665
Merge branch 'main' into remove-markdown
sarah11918 Jul 25, 2022
df569c2
Add to migration guide
matthewp Jul 25, 2022
dda13aa
Small pitch for MDX
matthewp Jul 25, 2022
ece548e
Update src/pages/en/migrate.md
matthewp Jul 26, 2022
f8564c1
Update src/pages/en/migrate.md
matthewp Jul 26, 2022
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
89 changes: 1 addition & 88 deletions src/pages/en/guides/markdown-content.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -345,93 +345,6 @@ const { Content } = Astro.props.post
<Content/>
</article>
```
## Markdown Component

:::caution[Deprecated]
The `<Markdown />` component does not work in SSR and will be moved to its own package before v1.0. Consider [importing Markdown content](/en/guides/markdown-content/#importing-markdown) instead.
:::

You can import the [built-in Astro Markdown component](/en/reference/api-reference/#markdown-) in your component script and then write any Markdown you want between `<Markdown></Markdown>` tags.

````astro
---
import { Markdown } from 'astro/components';
import Layout from '../layouts/Layout.astro';

const expressions = 'Lorem ipsum';
---
<Layout>
<Markdown>
# Hello world!

**Everything** supported in a `.md` file is also supported here!

There is _zero_ runtime overhead.

In addition, Astro supports:
- Astro {expressions}
- Automatic indentation normalization
- Automatic escaping of expressions inside code blocks

```js
// This content is not transformed!
const object = { someOtherValue };
```

- Rich component support like any `.astro` file!
- Recursive Markdown support (Component children are also processed as Markdown)
</Markdown>
</Layout>
````

### Remote Markdown

:::caution[Deprecated]
The `<Markdown />` component does not work in SSR and will be moved to its own package before v1.0. Consider [importing Markdown content](/en/guides/markdown-content/#importing-markdown) instead.
:::

If you have Markdown in a remote source, you may pass it directly to the Markdown component through the `content` attribute.

```astro
---
import { Markdown } from 'astro/components';

const content = await fetch('https://raw.githubusercontent.com/withastro/docs/main/README.md').then(res => res.text());
---
<Layout>
<Markdown content={content} />
</Layout>
```

### Nested Markdown

:::caution[Deprecated]
The `<Markdown />` component does not work in SSR and will be moved to its own package before v1.0. Consider [importing Markdown content](/en/guides/markdown-content/#importing-markdown) instead.
:::

`<Markdown />` components can be nested.

```astro
---
import { Markdown } from 'astro/components';

const content = await fetch('https://raw.githubusercontent.com/withastro/docs/main/README.md').then(res => res.text());
---

<Layout>
<Markdown>
## Markdown example

Here we have some __Markdown__ code. We can also dynamically render remote content.

<Markdown content={content} />
</Markdown>
</Layout>
```

:::caution
Use of the `Markdown` component to render remote Markdown can open you up to a [cross-site scripting (XSS)](https://en.wikipedia.org/wiki/Cross-site_scripting) attack. If you are rendering untrusted content, be sure to _sanitize your content **before** rendering it_.
:::

## Configuring Markdown

Expand Down Expand Up @@ -491,7 +404,7 @@ By default, Astro comes with [GitHub-flavored Markdown](https://github.com/remar

Astro comes with built-in support for [Shiki](https://shiki.matsu.io/) and [Prism](https://prismjs.com/). This provides instant syntax highlighting for:

- all code fences (\`\`\`) used in a markdown (`.md`) file and the [built-in `<Markdown />` component](#markdown-component).
- all code fences (\`\`\`) used in a markdown (`.md`) file.
- content within the [built-in `<Code />` component](/en/reference/api-reference/#code-) (powered by Shiki), or the [`<Prism />` component](/en/reference/api-reference/#prism-) (powered by Prism).

Shiki is enabled by default, preconfigured with the `github-dark` theme. The compiled output will be limited to inline `style`s without any extraneous CSS classes, stylesheets, or client-side JS.
Expand Down
4 changes: 4 additions & 0 deletions src/pages/en/migrate.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,10 @@ Astro no longer supports components or JSX expressions in Markdown pages by defa

To make migrating easier, a new [legacy flag](/en/reference/configuration-reference/#legacyastroflavoredmarkdown) can be used to re-enable previous Markdown features.

### `<Markdown />` Component Removed

If you were previously using Astro’s built-in `<Markdown />` component, this has been moved to a separate package. You will now need to install `@astrojs/markdown` and update your imports accordingly. For more details, see [the `@astrojs/markdown` README](https://github.com/withastro/astro/tree/main/packages/markdown/component).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @matthewp !

@delucis , I'm assuming that this @astrojs/markdown component does NOT get automatically added to our Integrations page?

  • Do we want a legacy package on our integrations page, so that we don't need to send people externally to the README but can instead have a page in Docs? Or, do we specifically NOT want this showing up in Docs, because we don't want people using it unless they really have to?

  • Do we want to take this opportunity here in the migration guide to encourage people to transition to MDX, or simply say, "Here's where the new package is?"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we don't want people using it unless they really have to.

Agree that it's a good opportunity to push people towards MDX, I'll add that.


## Migrate to v1.0.0-beta

On April 4, 2022 we released the Astro 1.0 Beta! 🎉
Expand Down
17 changes: 1 addition & 16 deletions src/pages/en/reference/api-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -436,22 +436,7 @@ Astro includes several built-in components for you to use in your projects. All

### `<Markdown />`

:::caution[Deprecated]
The `<Markdown />` component does not work in SSR and will be moved to its own package before v1.0. Consider [importing Markdown content](/en/guides/markdown-content/#importing-markdown) instead.
:::

```astro
---
import { Markdown } from 'astro/components';
---
<Markdown>
# Markdown syntax is now supported! **Yay!**
</Markdown>
```

See our [Markdown Guide](/en/guides/markdown-content/) for more info.

<!-- TODO: We should move some of the specific component info here. -->
The Markdown component is no longer built into Astro.

### `<Code />`

Expand Down
2 changes: 0 additions & 2 deletions src/pages/en/reference/directives-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -221,8 +221,6 @@ Using `define:vars` on a `<script>` or `<style>` tag implies the [`is:inline` di

`is:raw` instructs the Astro compiler to treat any children of that element as text. This means that all special Astro templating syntax will be ignored inside of this component.

Used internally by the `<Markdown />` component.

For example, if you had a custom Katex component that converted some text to HTML, you could have users do this:

```astro
Expand Down