Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/natemoo-re/astro-remote
Render remote HTML or Markdown content in Astro with full control over the output
https://github.com/natemoo-re/astro-remote
Last synced: 18 days ago
JSON representation
Render remote HTML or Markdown content in Astro with full control over the output
- Host: GitHub
- URL: https://github.com/natemoo-re/astro-remote
- Owner: natemoo-re
- License: mit
- Created: 2022-08-07T04:51:02.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-08-07T19:14:29.000Z (3 months ago)
- Last Synced: 2024-10-05T13:59:50.558Z (29 days ago)
- Language: Astro
- Homepage:
- Size: 224 KB
- Stars: 176
- Watchers: 6
- Forks: 9
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- my-awesome-astro - astro-remote - (Recommended) SSR, render remote markdown content in Astro with full control over the output including adding components. Does not inherit markdown setttings from Astro config (What Do I Use... / If I want to render a string of markdown?)
README
# Astro Remote
[](https://npm.im/astro-remote)
Render remote HTML or Markdown content in Astro with full control over the output.
Powered by [`ultrahtml`](https://github.com/natemoo-re/ultrahtml) and [`marked`](https://github.com/markedjs/marked).
## Install
```sh
npm install astro-remote
pnpm install astro-remote
yarn install astro-remote
```
## Rendering Remote Content
The most basic function of `astro-remote` is to convert a string of HTML or Markdown to HTML. Use the `Markup` and `Markdown` components depending on your input.
```astro
---
import { Markup, Markdown } from 'astro-remote';
const { html, markdown } = await fetch('http://my-site.com/api/v1/post').then(res => res.json());
---
```
### Sanitization
By default, all HTML content will be sanitized with sensible defaults (`script` blocks are dropped). This can be controlled using the [`SanitizeOptions`](https://github.com/natemoo-re/ultrahtml/blob/71e723f6093abea2584c9ea3bfecc0ce68d02d8d/src/index.ts#L251-L268) available in `ultrahtml`. Set to `false` to disable sanitization.
```astro
---
import { Markup } from 'astro-remote';
const content = await fetch('http://my-site.com/api/v1/post').then(res => res.text());
---
```
### Customization
Both `Markup` and `Markdown` allow full control over the rendering of output. The `components` option allows you to replace a standard HTML element with a custom component.
```astro
---
import { Markdown, Markup } from 'astro-remote';
import Title from '../components/Title.astro';
const content = await fetch('http://my-site.com/api/v1/post').then(res => res.text());
---
```
In addition to built-in HTML Elements, `Markdown` also supports a few custom components for convenience.
#### ``
The `Heading` component renders all `h1` through `h6` elements. It receives the following props:
- `as`, the `h1` through `h6` tag
- `href`, a pre-generated, slugified `href`
- `text`, the text content of the children (for generating a custom slug)
```astro
---
import { Markdown } from 'astro-remote';
import Heading from '../components/Heading.astro';
const content = await fetch('http://my-site.com/api/v1/post').then(res => res.text());
---
```
A sample `Heading` component might look something like this.
```astro
---
const { as: Component, href } = Astro.props;
---
#### ``
The `CodeBlock` component allows you customize the rendering of code blocks. It receives the following props:
- `lang`, the language specified after the three backticks (defaults to `plaintext`)
- `code`, the raw code to be highlighted. **Be sure to escape the output!**
- `...props`, any other attributes passed to the three backticks. These should follow HTML attribute format (`name="value"`)
A sample `CodeBlock` component might look something like this.
```astro
---
const { lang, code, ...props } = Astro.props;
const highlighted = await highlight(code, { lang });
---
```
#### ``
The `CodeSpan` component allows you customize the rendering of inline code spans. It receives the following props:
- `code`, the value of the code span
A sample `CodeSpan` component might look something like this.
```astro
---
const { code } = Astro.props;
---
```
#### ``
The `Note` component allows you customize the rendering of GitHub-style notes and warnings. It receives the following props:
- `type`, either `"note"` or `"warning"`
To use a `Note` component in Markdown, use the following syntax:
```md
> **Note**
> Some tip here!
> **Warning**
> Some warning here!
```
### Custom Components in Markdown
If you'd like to allow custom components in Markdown, you can do so using a combination of the `sanitize` and `components` options. By default, sanitization removes components.
Given the following markdown source:
```markdown
# Hello world!
It works!
```
```astro
---
import { Markdown } from 'astro-remote';
import MyCustomComponent from '../components/MyCustomComponent.astro';
const content = await fetch('http://my-site.com/api/v1/post').then(res => res.text());
---
```
### Using Marked Extensions
If you'd like to extend the underlying [Marked](https://marked.js.org/using_pro) behavior, the `marked` prop accepts `extensions`.
```astro
---
import { Markdown } from 'astro-remote';
import markedAlert from 'marked-alert'
const content = await fetch('http://my-site.com/api/v1/post').then(res => res.text());
---
```