Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
65 changes: 38 additions & 27 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,23 @@
> [!IMPORTANT]
> This is a fork of [@astropub/md](https://github.com/astro-community/md) — all the original hard work was done by its authors. This fork swaps the rendering engine from remark/rehype to **[Sätteri](https://satteri.bruits.org/)** (a Rust-backed Markdown pipeline) and targets **Astro 7**.

# Astro Markdown <img src="https://jonneal.dev/astro-logo.svg" alt="" width="90" height="90" align="right">

**Astro Markdown** lets you render any Markdown content in **[Astro](https://astro.build)**, optionally integrating with any existing configuration.
**Astro Markdown** lets you render any Markdown content in **[Astro](https://astro.build)**, powered by **[Sätteri](https://satteri.bruits.org/)**.

[![NPM Version][npm-img]][npm-url]
[![NPM Downloads][download-img]][download-url]
[![Open in StackBlitz][stackblitz-img]][stackblitz-url]

```astro
---
import { Markdown } from '@astropub/md'
import { Markdown } from '@mashehu/astropub-md'
---
<Markdown of={`# Hi, there!` /* Renders `<h1>Hi, there!</h1>` */} />
```

```astro
---
import { markdown } from '@astropub/md'
import { markdown } from '@mashehu/astropub-md'
---
{
/* Renders `<h1>Hi, there!</h1>` */
Expand All @@ -28,14 +30,14 @@ import { markdown } from '@astropub/md'
Add **Astro Markdown** to your project.

```shell
npm install @astropub/md
npm install @mashehu/astropub-md
```

Use **Astro Markdown** in your project.

```astro
---
import { markdown } from '@astropub/md'
import { markdown } from '@mashehu/astropub-md'
---
<html lang="en">
<head>
Expand All @@ -53,33 +55,45 @@ Welcome to my _website_.`
</html>
```

Optionally, integrate **Astro Markdown** with your existing Astro configuration.
Optionally, add the integration. It inherits the relevant parts of your Astro `markdown` configuration (`gfm` and `smartypants`) and lets you pass [Sätteri](https://satteri.bruits.org/) options directly.

```js
// astro.config.js
import { defineConfig } from 'astro/config'
import markdownIntegration from '@astropub/md'
import markdownIntegration from '@mashehu/astropub-md'

export default defineConfig({
integrations: [
markdownIntegration(),
markdownIntegration({
// Sätteri `CompileOptions` — applied to every render
features: {
gfm: true,
smartPunctuation: true,
// math: true,
// wikilinks: true,
},
// mdastPlugins: [],
// hastPlugins: [],
}),
],
markdown: {
remarkPlugins: [],
rehypePlugins: [],
// syntaxHighlight: 'shiki'
// syntaxHighlight: 'prism'
}
// `gfm` and `smartypants` are mapped onto Sätteri features automatically
gfm: true,
smartypants: true,
},
})
```

Now `markdown` configuration is automatically applied to `<Markdown>` components and `markdown()` functions.
> [!NOTE]
> Sätteri does **not** use the remark/rehype ecosystem, so Astro's `remarkPlugins`, `rehypePlugins`, and `syntaxHighlight` options have no effect here. Use Sätteri's own [`mdastPlugins` / `hastPlugins`](https://satteri.bruits.org/) instead, passed to `markdownIntegration()` or per call as the second argument to `markdown()`.

Now that configuration is automatically applied to `<Markdown>` components and `markdown()` functions.

Use `markdown.inline()` or `<Markdown.Inline>` to handle short strings of text without the surrounding paragraph.

```astro
---
import { Markdown } from '@astropub/md'
import { Markdown } from '@mashehu/astropub-md'
---
<Markdown.Inline of={
/* Renders `Welcome to my <em>website</em>.` */
Expand All @@ -89,7 +103,7 @@ import { Markdown } from '@astropub/md'

```astro
---
import { markdown } from '@astropub/md'
import { markdown } from '@mashehu/astropub-md'
---
{await markdown.inline(
/* Renders `Welcome to my <em>website</em>.` */
Expand Down Expand Up @@ -119,7 +133,7 @@ Inside of this Astro project, you'll see the following folders and files:
└── ...etc
```

This project uses **workspaces** to develop a single package, `@astropub/md`.
This project uses **workspaces** to develop a single package, `@mashehu/astropub-md`.

It also includes a minimal Astro project, `demo`, for developing and demonstrating the component.

Expand All @@ -135,16 +149,13 @@ All commands are run from the root of the project, from a terminal:
| `npm run serve` | Preview your build locally, before deploying |

Want to learn more?
Read the [Astro documentation][docs-url] or jump into the [Astro Discord][chat-url].
Read the [Sätteri documentation][satteri-url], the [Astro documentation][docs-url], or jump into the [Astro Discord][chat-url].

[chat-url]: https://astro.build/chat
[docs-url]: https://github.com/withastro/astro
[satteri-url]: https://satteri.bruits.org/

[npm-img]: https://img.shields.io/npm/v/@astropub/md?color=%23444&label=&labelColor=%23CB0000&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjE1MCAxNTAgNDAwIDQwMCIgZmlsbD0iI0ZGRiI+PHBhdGggZD0iTTE1MCA1NTBoMjAwVjI1MGgxMDB2MzAwaDEwMFYxNTBIMTUweiIvPjwvc3ZnPg==&style=for-the-badge
[npm-url]: https://www.npmjs.com/package/@astropub/md
[stackblitz-img]: https://img.shields.io/badge/-Open%20in%20Stackblitz-%231374EF?color=%23444&labelColor=%231374EF&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjEwIDggMTIgMTgiIGhlaWdodD0iMTgiIGZpbGw9IiNGRkYiPjxwYXRoIGQ9Ik0xMCAxNy42aDUuMmwtMyA3LjRMMjIgMTQuNGgtNS4ybDMtNy40TDEwIDE3LjZaIi8+PC9zdmc+&style=for-the-badge
[stackblitz-url]: https://stackblitz.com/github/astro-community/md
[bundlejs-img]: https://img.shields.io/badge/dynamic/json?url=https://bundlejs.com/api?q=@astropub/md&query=size.totalCompressedSize&color=%23444&labelColor=%233B82F6&label=&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA3MDAgNzAwIiBmaWxsPSIjRkZGIj4KCTxwYXRoIGQ9Ik0xNDYgMkExNzEgMTcxIDAgMCAwIDMgMTM5bC0yIDExdjQwMmwyIDExYzE1IDcyIDcxIDEyNSAxNDMgMTM2bDIwOSAxIDE5OS0xIDktMmM3MC0xNiAxMTktNjYgMTM0LTEzNWwyLTEwVjE1MGwtMi0xMkExNzEgMTcxIDAgMCAwIDU2MiAzbC0xMC0yLTE5OS0xQzE4NyAwIDE1MyAwIDE0NiAyem0xODEgMjUxdjM2bDctM2MxMy02IDMzLTkgNTAtNyA0MSA1IDcwIDM0IDgwIDc4IDIgMTIgMiA0MSAwIDUzLTUgMjItMTMgMzgtMjcgNTJhODIgODIgMCAwIDEtNjMgMjZjLTE1IDAtMTkgMC0yNS0yLTEwLTItMTctNi0yNC0xMGwtNS0zdjExaC00NVYyMTdoNTJ2MzZ6bTI5IDcxYy0yMCAzLTMyIDE5LTM1IDQ4LTMgMjUgMyA0OCAxNCA2MCA1IDYgMTMgMTAgMjMgMTEgMjUgNCA0NC05IDUxLTM2bDMtMTljMC0xNy0xLTI3LTctMzktOS0xOS0yNi0yOC00OS0yNXoiLz4KPC9zdmc+&style=for-the-badge
[bundlejs-url]: https://bundlejs.com/?bundle&q=@astropub/md
[download-url]: https://www.npmjs.com/package/@astropub/md
[download-img]: https://img.shields.io/badge/dynamic/json?url=https://api.npmjs.org/downloads/point/last-week/@astropub/md&query=downloads&label=⇓+week&color=%23444&labelColor=%23EEd100&style=for-the-badge
[npm-img]: https://img.shields.io/npm/v/@mashehu/astropub-md?color=%23444&label=&labelColor=%23CB0000&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjE1MCAxNTAgNDAwIDQwMCIgZmlsbD0iI0ZGRiI+PHBhdGggZD0iTTE1MCA1NTBoMjAwVjI1MGgxMDB2MzAwaDEwMFYxNTBIMTUweiIvPjwvc3ZnPg==&style=for-the-badge
[npm-url]: https://www.npmjs.com/package/@mashehu/astropub-md
[download-url]: https://www.npmjs.com/package/@mashehu/astropub-md
[download-img]: https://img.shields.io/badge/dynamic/json?url=https://api.npmjs.org/downloads/point/last-week/@mashehu/astropub-md&query=downloads&label=⇓+week&color=%23444&labelColor=%23EEd100&style=for-the-badge
2 changes: 1 addition & 1 deletion demo/astro.config.js
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { defineConfig } from 'astro/config'
import markdownIntegration from '@astropub/md'
import markdownIntegration from '@mashehu/astropub-md'

export default defineConfig({
integrations: [
Expand Down
7 changes: 4 additions & 3 deletions demo/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,8 @@
"astro": "astro"
},
"devDependencies": {
"@astropub/md": "*",
"astro": "4"
}
"@mashehu/astropub-md": "*",
"astro": "7"
},
"version": "3.0.0"
}
2 changes: 1 addition & 1 deletion demo/src/pages/index.astro
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
import { Markdown, markdown } from '@astropub/md'
import { Markdown, markdown } from '@mashehu/astropub-md'
---
<html lang="en">
<head>
Expand Down
7 changes: 4 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@
"start": "cd demo; astro dev",
"build": "cd demo; astro build",
"serve": "cd demo; astro preview",
"release": "npm --workspaces publish --access public"
"release": "npm --workspaces packages/md --access public"
},
"prettier": {
"semi": false,
Expand All @@ -25,7 +25,8 @@
"startCommand": "npm start"
},
"devDependencies": {
"astro": "4",
"astro": "7",
"types-object": "latest"
}
},
"version": "3.0.0"
}
63 changes: 37 additions & 26 deletions packages/md/README.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,23 @@
> [!IMPORTANT]
> This is a fork of [@astropub/md](https://github.com/astro-community/md) — all the original hard work was done by its authors. This fork swaps the rendering engine from remark/rehype to **[Sätteri](https://satteri.bruits.org/)** (a Rust-backed Markdown pipeline) and targets **Astro 7**.

# Astro Markdown <img src="https://jonneal.dev/astro-logo.svg" alt="" width="90" height="90" align="right">

**Astro Markdown** lets you render any Markdown content in **[Astro](https://astro.build)**, optionally integrating with any existing configuration.
**Astro Markdown** lets you render any Markdown content in **[Astro](https://astro.build)**, powered by **[Sätteri](https://satteri.bruits.org/)**.

[![NPM Version][npm-img]][npm-url]
[![NPM Downloads][download-img]][download-url]
[![Open in StackBlitz][stackblitz-img]][stackblitz-url]

```astro
---
import { Markdown } from '@astropub/md'
import { Markdown } from '@mashehu/astropub-md'
---
<Markdown of={`# Hi, there!` /* Renders `<h1>Hi, there!</h1>` */} />
```

```astro
---
import { markdown } from '@astropub/md'
import { markdown } from '@mashehu/astropub-md'
---
{
/* Renders `<h1>Hi, there!</h1>` */
Expand All @@ -28,14 +30,14 @@ import { markdown } from '@astropub/md'
Add **Astro Markdown** to your project.

```shell
npm install @astropub/md
npm install @mashehu/astropub-md
```

Use **Astro Markdown** in your project.

```astro
---
import { markdown } from '@astropub/md'
import { markdown } from '@mashehu/astropub-md'
---
<html lang="en">
<head>
Expand All @@ -53,33 +55,45 @@ Welcome to my _website_.`
</html>
```

Optionally, integrate **Astro Markdown** with your existing Astro configuration.
Optionally, add the integration. It inherits the relevant parts of your Astro `markdown` configuration (`gfm` and `smartypants`) and lets you pass [Sätteri](https://satteri.bruits.org/) options directly.

```js
// astro.config.js
import { defineConfig } from 'astro/config'
import markdownIntegration from '@astropub/md'
import markdownIntegration from '@mashehu/astropub-md'

export default defineConfig({
integrations: [
markdownIntegration(),
markdownIntegration({
// Sätteri `CompileOptions` — applied to every render
features: {
gfm: true,
smartPunctuation: true,
// math: true,
// wikilinks: true,
},
// mdastPlugins: [],
// hastPlugins: [],
}),
],
markdown: {
remarkPlugins: [],
rehypePlugins: [],
// syntaxHighlight: 'shiki'
// syntaxHighlight: 'prism'
}
// `gfm` and `smartypants` are mapped onto Sätteri features automatically
gfm: true,
smartypants: true,
},
})
```

Now `markdown` configuration is automatically applied to `<Markdown>` components and `markdown()` functions.
> [!NOTE]
> Sätteri does **not** use the remark/rehype ecosystem, so Astro's `remarkPlugins`, `rehypePlugins`, and `syntaxHighlight` options have no effect here. Use Sätteri's own [`mdastPlugins` / `hastPlugins`](https://satteri.bruits.org/) instead, passed to `markdownIntegration()` or per call as the second argument to `markdown()`.

Now that configuration is automatically applied to `<Markdown>` components and `markdown()` functions.

Use `markdown.inline()` or `<Markdown.Inline>` to handle short strings of text without the surrounding paragraph.

```astro
---
import { Markdown } from '@astropub/md'
import { Markdown } from '@mashehu/astropub-md'
---
<Markdown.Inline of={
/* Renders `Welcome to my <em>website</em>.` */
Expand All @@ -89,7 +103,7 @@ import { Markdown } from '@astropub/md'

```astro
---
import { markdown } from '@astropub/md'
import { markdown } from '@mashehu/astropub-md'
---
{await markdown.inline(
/* Renders `Welcome to my <em>website</em>.` */
Expand All @@ -104,16 +118,13 @@ Enjoy!
---

Want to learn more?
Read the [Astro documentation][docs-url] or jump into the [Astro Discord][chat-url].
Read the [Sätteri documentation][satteri-url], the [Astro documentation][docs-url], or jump into the [Astro Discord][chat-url].

[chat-url]: https://astro.build/chat
[docs-url]: https://github.com/withastro/astro
[satteri-url]: https://satteri.bruits.org/

[npm-img]: https://img.shields.io/npm/v/@astropub/md?color=%23444&label=&labelColor=%23CB0000&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjE1MCAxNTAgNDAwIDQwMCIgZmlsbD0iI0ZGRiI+PHBhdGggZD0iTTE1MCA1NTBoMjAwVjI1MGgxMDB2MzAwaDEwMFYxNTBIMTUweiIvPjwvc3ZnPg==&style=for-the-badge
[npm-url]: https://www.npmjs.com/package/@astropub/md
[stackblitz-img]: https://img.shields.io/badge/-Open%20in%20Stackblitz-%231374EF?color=%23444&labelColor=%231374EF&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjEwIDggMTIgMTgiIGhlaWdodD0iMTgiIGZpbGw9IiNGRkYiPjxwYXRoIGQ9Ik0xMCAxNy42aDUuMmwtMyA3LjRMMjIgMTQuNGgtNS4ybDMtNy40TDEwIDE3LjZaIi8+PC9zdmc+&style=for-the-badge
[stackblitz-url]: https://stackblitz.com/github/astro-community/md
[bundlejs-img]: https://img.shields.io/badge/dynamic/json?url=https://bundlejs.com/api?q=@astropub/md&query=size.totalCompressedSize&color=%23444&labelColor=%233B82F6&label=&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA3MDAgNzAwIiBmaWxsPSIjRkZGIj4KCTxwYXRoIGQ9Ik0xNDYgMkExNzEgMTcxIDAgMCAwIDMgMTM5bC0yIDExdjQwMmwyIDExYzE1IDcyIDcxIDEyNSAxNDMgMTM2bDIwOSAxIDE5OS0xIDktMmM3MC0xNiAxMTktNjYgMTM0LTEzNWwyLTEwVjE1MGwtMi0xMkExNzEgMTcxIDAgMCAwIDU2MiAzbC0xMC0yLTE5OS0xQzE4NyAwIDE1MyAwIDE0NiAyem0xODEgMjUxdjM2bDctM2MxMy02IDMzLTkgNTAtNyA0MSA1IDcwIDM0IDgwIDc4IDIgMTIgMiA0MSAwIDUzLTUgMjItMTMgMzgtMjcgNTJhODIgODIgMCAwIDEtNjMgMjZjLTE1IDAtMTkgMC0yNS0yLTEwLTItMTctNi0yNC0xMGwtNS0zdjExaC00NVYyMTdoNTJ2MzZ6bTI5IDcxYy0yMCAzLTMyIDE5LTM1IDQ4LTMgMjUgMyA0OCAxNCA2MCA1IDYgMTMgMTAgMjMgMTEgMjUgNCA0NC05IDUxLTM2bDMtMTljMC0xNy0xLTI3LTctMzktOS0xOS0yNi0yOC00OS0yNXoiLz4KPC9zdmc+&style=for-the-badge
[bundlejs-url]: https://bundlejs.com/?bundle&q=@astropub/md
[download-url]: https://www.npmjs.com/package/@astropub/md
[download-img]: https://img.shields.io/badge/dynamic/json?url=https://api.npmjs.org/downloads/point/last-week/@astropub/md&query=downloads&label=⇓+week&color=%23444&labelColor=%23EEd100&style=for-the-badge
[npm-img]: https://img.shields.io/npm/v/@mashehu/astropub-md?color=%23444&label=&labelColor=%23CB0000&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjE1MCAxNTAgNDAwIDQwMCIgZmlsbD0iI0ZGRiI+PHBhdGggZD0iTTE1MCA1NTBoMjAwVjI1MGgxMDB2MzAwaDEwMFYxNTBIMTUweiIvPjwvc3ZnPg==&style=for-the-badge
[npm-url]: https://www.npmjs.com/package/@mashehu/astropub-md
[download-url]: https://www.npmjs.com/package/@mashehu/astropub-md
[download-img]: https://img.shields.io/badge/dynamic/json?url=https://api.npmjs.org/downloads/point/last-week/@mashehu/astropub-md&query=downloads&label=⇓+week&color=%23444&labelColor=%23EEd100&style=for-the-badge
2 changes: 1 addition & 1 deletion packages/md/global.d.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
declare module "@astropub/md/Markdown" {
declare module "@mashehu/astropub-md/Markdown" {
export var Markdown: typeof import('./lib/component')['Markdown']

export default Markdown
Expand Down
2 changes: 0 additions & 2 deletions packages/md/lib/component.js
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ export const Markdown = Object.assign(
if (typeof mdl === 'string') {
yield await markdown(mdl, {
fileURL: new URL(import.meta.url),
contentDir: new URL('./', import.meta.url),
})
} else {
yield renderSlot(result, slots.default)
Expand All @@ -35,7 +34,6 @@ export const Markdown = Object.assign(
if (typeof mdl === 'string') {
yield await markdown.inline(mdl, {
fileURL: new URL(import.meta.url),
contentDir: new URL('./', import.meta.url),
})
} else {
yield renderSlot(result, slots.default)
Expand Down
3 changes: 0 additions & 3 deletions packages/md/lib/html-string.d.ts

This file was deleted.

5 changes: 0 additions & 5 deletions packages/md/lib/html-string.js

This file was deleted.

3 changes: 2 additions & 1 deletion packages/md/lib/integration.d.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import type { AstroIntegration } from 'astro'
import type { CompileOptions } from 'satteri'

export function mdAstro(): AstroIntegration
export function mdAstro(options?: CompileOptions): AstroIntegration

export type { AstroIntegration }
25 changes: 22 additions & 3 deletions packages/md/lib/integration.js
Original file line number Diff line number Diff line change
@@ -1,11 +1,30 @@
import { shared } from './shared.js'

export function mdAstro() {
/**
* Astro integration that hands the host project's Markdown configuration to the
* Sätteri renderer used by `markdown()` / `<Markdown>`.
*
* Astro's `config.markdown` is shaped for the remark/rehype pipeline, which
* Sätteri does not use. We map the options that have a Sätteri equivalent
* (`gfm`, `smartypants`) onto Sätteri's feature flags. remark/rehype plugins
* have no Sätteri equivalent and are ignored — pass Sätteri `mdastPlugins` /
* `hastPlugins` to `mdAstro()` instead.
*/
export function mdAstro(/** @type {CompileOptions} */ options = {}) {
const integration = /** @type {AstroIntegration} */ ({
name: 'astro:md',
hooks: {
'astro:config:done'({ config }) {
shared.markdownConfig = config.markdown
const md = config.markdown || {}

shared.markdownConfig = {
...options,
features: {
gfm: md.gfm ?? true,
smartPunctuation: md.smartypants ?? true,
...options.features,
},
}
},
},
})
Expand All @@ -14,4 +33,4 @@ export function mdAstro() {
}

/** @typedef {import('astro').AstroIntegration} AstroIntegration */
/** @typedef {import('vite').Plugin} Plugin */
/** @typedef {import('satteri').CompileOptions} CompileOptions */
Loading